Good first issues

Flory, Justin W.

License: CC BY-SA 4.0

This Mission is a guide to making "good first issues" (shortened to G.F.I.'s) for your Open Source community. To create good GFIs, we will explore these Objectives for this Mission:

  1. GFIs exist

  2. Assignee ratio

  3. Simple language

  4. Actionable

  5. Purpose

  6. Deadlines

  7. Low committment

  8. References

GFIs exist

The first requirement to having good GFIs is to… create GFIs!

In the case of writing new GFIs, it is usually better to publish something sooner than later, and not overthink it. For an individual "core" repository (however you measure that), you should have 3-5 unassigned GFIs for new contributors. Having a few different GFIs gives people options to try different things based on their comfort and experience. What is easy to one person may not be easy to another.

Unless your project is already large and has a big community, limit no more than five GFIs per core repository. It is good to have opportunity, but you also do not want to overwhelm a new contributor with so many choices. They are still learning about your project, so it is better to be simple.

Assignee ratio

Having GFIs is helpful, but making sure people can actually volunteer for them is important too. Make sure more of your GFIs (>60%) are unassigned.

If you have GFIs on your project, you want to make sure people are invited to work on them. If someone is working on a GFI, they should be added as the assignee. If you have more assigned issues than unassigned issues, that is a sign to make more GFIs.

Simple language

Open source is international. Whatever language you use, keep it simple and avoid complicated words.

Sometimes it is hard to use simple language for a project. Do your best attempt. A good way to double-check is to ask someone else to read for comprehension and get their feedback. Since GFIs are for new contributors, it is important to keep the language beginner-friendly.

(Si tu proyecto fuera en español, yo necesitaría tu ayuda para usar palabras sencillas para entender lo que quieres. ¡Ya que no soy un hispanohablante nativo!)

Actionable

GFIs should be easy to tell if they are "done" or not. Define closing / success criteria up front in GFI descriptions.

A new contributor will not understand your project the same way as a lead developer. What is obvious to an experienced team member is not always obvious to a newcomer. So, make it easy for a newcomer to understand what success looks like. Is it a different look in the front-end? Is it a specific output in the terminal? Be clear in what you are looking for in a contribution to avoid wasted time.

Purpose

Anyone who contributes to a project wants their contribution to count. Make sure GFIs add real benefits or improvements to your project.

There are many things that motivate Open Source contributors. One motivation is knowing that an improvement or change is useful or helpful to a project. Few people will want to work on something that does not have real, added value to your project. So, do your best to make sure GFIs have some real purpose in the project, even if it is small.

This can also help to "level up" a new contributor to bigger and larger tasks. Adding an improvement and seeing its impact in the project is a great feeling! They may have increased confidence to work up to bigger things in your project.

Deadlines

GFIs do not need absolute, hard deadlines. But make sure GFIs have a rough estimate or timeline for completion.

Deadlines are helpful for a few reasons:

  1. Keeps a contributor accountable to completing work

  2. Easier for maintainers to follow up and open a task back up to the community, if needed

  3. Outside contributors can find more useful work to contribute to

The purpose of deadlines is not to give someone a hard requirement they must meet. Be flexible and be kind, especially if they are a volunteer or unpaid to work on your project. Loose deadlines can be an effective tool for a contributor to pace themselves on new work. They also make sure new contributors get to work on something that is more immediately useful to the project, instead of something that is a more distant or future goal.

Low committment

Finally, keep the bar low for commitment. Encourage new contributors to take on new work, but avoid adding serious pressure on them for completing a GFI.

If someone volunteers to work on a GFI and does not complete it, this should not be a problem. GFIs are usually "nice to have" tasks. They should not have impacts to product delivery time or important milestones. (They can be related to important milestones, so long as they are not major work commitments.)

Be kind if someone does need to drop a GFI. There are any number of reasons they might not complete the work. It is okay to ask someone if they need help, or why they did not complete the work. But do not pressure them to finish the work or complete it if they are unsure.

References

Find more practical examples of GFIs and other useful resources below:

Resources & tools

  • First Timers Only: Combined resource featuring several different sites, resources, and other links.

  • Fedora Project easyfix: List of tasks in the Fedora Project that were evaluated to have easy entrance points for new contributors.

  • Up For Grabs: List of projects with curated tasks specifically for new contributors. You can also add your project’s GFIs here once you have some.