Between creating a repo to help git & Github beginners understand common workflows (more on that later), and helping onboard more experienced folks to new projects recently, this question's been at the forefront of my mind.
What Makes a Good First Issue?
The first thing to think about is: what's the point of a good first issue? Well, the general point is to teach whoever addresses the issue something that will empower them to contribute to something more complex afterwards.
So really, the point is to isolate modules of the learning process for the contributor into digestible portions that increase their independence in the codebase.
Scaffolding and the Zone of Proximal Development
Back when I was teaching elementary school, this was called "scaffolding". The term was coined by a psychologist named Lev Vygotsky. He also outlined something called the "zone of proximal development".
This is the area between what a learner can do independently, and what they can't do at all. In other words, the zone of proximal development represents a place where a learner might need some assistance. Too much assistance, and they won't expand the number of things they can do independently. Too little, and they'll get frustrated and give up.
The learner needs a scaffold to climb.
What This Theory Means For First Issues
So, a good first issue is essentially a relative definition because it depends on where the learner is with respect to the subject.
For example, if the person I'm targeting with my 'good first issue' is new to git & Github entirely, I'm not going to complicate the matter with much else besides an introduction to the basics of contributing. That means I might make my issue focused on adding something to a list of resources, or correcting a typo.
Then, once they've familiarized themselves with the git & Github requirements for a codebase, I might suggest adding a larger chunk of documentation. Adding to documentation makes a good first issue for many people because it often has a relatively low risk with respect to breaking the project, but it requires a relatively detailed knowledge of the subject matter.
But if someone is a git & Github expert, then for them, a "good first issue" might be something like adding testing, which again, perhaps has a lower risk attached to it, but requires getting to know the codebase, often specifically with respect to release processes and development environments. It then has the effect of isolating that aspect of codebase maintenance without overwhelming the newcomer.
If someone is familiar with the all the technologies involved with a codebase, but unfamiliar with the codebase itself, a "good second issue" might be refactoring. This will increase comfort with the codebase as it is completed.
Important Note
If the issue represents something in the coder's "zone of proximal development" then they will need some assistance to complete the task. This is a perfect place to 1) write a detailed ticket with some instructions on how to complete the task or 2) offer to pair. There might be other ways to help, too. Either way, leaving someone high and dry without assistance on a good first issue might trap them in the third zone of development.
On the flip side, a super 'easy' issue for someone to complete without any assistance at all might be something you would assign them to complete within a project for many valid reasons (getting stuff done at work quickly, you just need the help, etc), but it won't be to teach them anything. Learning requires moving out of a comfort zone and a bit of independent work and research as well.
Where To Go From Here
These are just some ideas I have for 'scaffolding' issues. I'd love to hear some more perspectives on them!
Top comments (1)
To search for simple tasks you can also use the service good-first-issues.github.io
This is an open source project github.com/good-first-issues/good-... that collects a list of issues labeled “good firts issue” and publishes them on GitHub Pages.