Creating Good First Issues

AMP welcomes new contributors and we want to make it as easy as possible for them to contribute. For many new contributors (who may not have open source/Git/AMP/etc. experience) it can be difficult to figure out how to get started.

To help these new contributors get oriented we curate Good First Issues. A Good First Issue is a starter issue that a new contributor can use to get comfortable contributing to the AMP Project.

We depend on experienced members of the community to identify bugs/features that would provide this orientation and to then create a well-documented Good First Issue for them.

Our approach is inspired by Hoodie which collects starter issues in their Hoodie Camp. See the Hoodie Camp Issues for many examples of what good first issues look like. (Hoodie's Welcoming Communities post is also a great read.)

Qualities of a Good First Issue

Keep these qualities in mind when creating your Good First Issues:

• You should have a good sense of exactly what is needed to resolve the issue. In fact it would probably be faster for you to just fix the issue than to create the Good First Issue but the benefits to the community make the cost of creating the Good First Issue worth it.
• Even issues that require a very small/straightforward fix can be Good First Issues. The focus of Good First Issues is not just about getting fixes in AMP; they are also a chance for new contributors to get set up with Git/GitHub, get familiar with building/making changes/testing in AMP and experience going through the Pull Request process.
• The issue should be P3. The issue may not get picked up right away and the person fixing it may encounter problems while working on it so it should be an issue we are okay with going unresolved for a while.
• New contributors have a variety of backgrounds; we should have a variety of Good First Issues. The goal isn't for each Good First Issue to be a good first issue for every new contributor. Some new contributors may have extensive web development experience but haven't used Git; some may know everything about Git & Pull Requests but don't have a lot of experience with web components. You can specify "What you will need to know" in the bug so new contributors can find a Good First Issue that matches their current experience.

How to create a Good First Issue

• When you identify an issue that would make a Good First Issue, create a new issue using the Good First Issues Template (inspired by Hoodie's template). Copy the raw markdown into your issue and follow the guidance in the comments.
• Add the Good First Issue label and add the issue to the Good First Issues milestone. (The redundancy is intentional. Most other open source projects use a label for tracking these types of issues, so we do too... but we also ensure every bug is triaged to the right milestone.)
• If you come across a good candidate for a Good First Issue but are momentarily unable to spend the time filling out the template add the GFI Candidate label to the issue. The time spent converting GFI Candidates to Good First Issues will pay off for the AMP Project so please remember to come back to issues you labeled as a GFI Candidate.

Next steps for your Good First Issue

• We ask new contributors to claim a Good First Issue by adding a comment. Please keep an eye out for these and respond as soon as possible on the issue welcoming the new contributor and letting them know they can ask you questions.
• Please add the GFI Claimed! label to the issue once someone claims it so others can quickly see that someone is working on it.
• Encourage the person working on the GFI to join the ampproject GitHub org, which will let us assign the GFI to them. (Alternatively you can let mrjoro know and he can send an invite to the new contributor directly.)
• Keep an eye on the new contributor's progress on the GFI, and offer to help if they seem stuck or if you haven't heard any updates in a few days.
• Once the GFI is complete help the new contributor find other projects to work on in AMP based on their interests.