Skip to content

🐣 Good First Issue Contribution Guidelines

This guide explains what qualifies as a “Good First Issue”, how to suggest new issues and how to participate by resolving good first issues. All our good first issues should be labeled with the good first issue label.

What is a Good First Issue?

A Good First Issue is a task that is suitable for newcomers to the project. It should be:

  • Well-defined: The issue should have a clear goal and scope.
  • Manageable: The task should be small enough to be completed in a reasonable amount of time (typically a few hours).
  • Educational: The issue should help the newcomer learn about the project and its codebase.
  • Non-critical: The issue should not involve critical functionality or complex dependencies.
  • Documented: The issue should include all necessary information, such as links to relevant documentation, code examples, and any prerequisites.

Examples of Good First Issues:

  • Documentation updates (typos, broken links, clarifying setup steps).
  • Adding or improving tests for small, isolated components.
  • Code style or linting improvements.
  • Simple bug fixes with clear reproduction steps.
  • Small feature enhancements (e.g., adding a config flag, improving log messages).

How to Create a Good First Issue

When creating a Good First Issue, the best is to follow our template:

## 🆕🐥 First Timers Only

This issue is reserved for people who have never contributed to [PROJECT](PROJECT URL) or any open source project in general.
We know that creating a pull request (PR) is a major barrier for new contributors.
The goal of this issue and all other issues labeled by **'good first issue'** is to help you make your first contribution to [PROJECT].

## 👾 Description of the issue

AT THIS SECTION YOU NEED TO DESCRIBE THE ISSUE IN A WAY THAT IS UNDERSTANDABLE TO NEW CONTRIBUTORS.
YOU MUST NOT ASSUME THAT SUCH CONTRIBUTORS HAVE ANY KNOWLEDGE ABOUT THE CODEBASE OR HIERO.
IT IS HELPFUL TO ADD LINKS TO THE RELEVANT DOCUMENTATION AND/OR CODE SECTIONS.

## 💡 Solution

AT THIS SECTION YOU NEED TO DESCRIBE THE STEPS NEEDED TO SOLVE THE ISSUE.
PLEASE BREAK DOWN THE STEPS AS MUCH AS POSSIBLE AND MAKE SURE THAT THEY ARE EASY TO FOLLOW.
IF POSSIBLE, ADD LINKS TO THE RELEVANT DOCUMENTATION AND/OR CODE SECTIONS.

### 👩‍💻 Implementation

AT THIS SECTION YOU NEED TO DESCRIBE THE TECHNICAL STEPS NEEDED TO SOLVE THE ISSUE.
PLEASE BREAK DOWN THE STEPS AS MUCH AS POSSIBLE AND MAKE SURE THAT THEY ARE EASY TO FOLLOW.
IF POSSIBLE, ADD LINKS TO THE RELEVANT DOCUMENTATION AND/OR CODE.

## 📋 Step by step guide to do a contribution

If you have never contributed to an open source project at GitHub, the following step-by-step guide will introduce you to the workflow.
More information and concrete samples for shell commands for each step can be found in our [CONTRIBUTING.md](PROJECT'S CONTRIBUTING.md FILE LINK) file.
A more detailed general documentation of the GitHub PR workflow can be found [here](https://github.com/firstcontributions/first-contributions/blob/master/README.md).

- [ ] **Claim this issue:** Comment below that you are interested in working on the issue
- [ ] **Wait for assignment:** A community member with the given rights will add you as an assignee of the issue
- [ ] **Work on the issue:** Follow the detailed description in our [CONTRIBUTING.md](PROJECT'S CONTRIBUTING.md FILE LINK) file.
- [ ] **You did it 🎉:** We will merge the fix in the main branch. Thanks for being part of the [PROJECT] community as an open-source contributor ❤️

## 🤔 Additional Information

If you have any questions about the topic of this issue, please ask us directly by adding a comment below.
Additionally, we invite you to join our community on our [Discord](PROJECT'S DISCORD LINK) server or attend our [public community calls](PROJECT's CALENDAR LINK).

A general manual about open-source contributions can be found [here](https://github.com/firstcontributions/first-contributions/blob/master/README.md).

Once you created the issue, please make sure to add the good first issue candidate label to it or request the maintainers of the project to do so. Please do not add the good first issue label directly, maintainers need to review all candidate issues before accepting them as good first issues.

How to Work on Good First Issues

Finding Good First Issues

  • Look for issues labeled with "good first issue" in the project's issue tracker (e.g., GitHub Issues).
  • Consult the project's CONTRIBUTING guide, which may contain a dedicated section or list of beginner-friendly tasks.
  • Engage with the project community on platforms like Slack or Discord to inquire about suitable issues for new contributors.

Collaborating and submitting your work in Good First Issues

  • Fork and Clone: Fork the project repository and clone it locally to your development environment.
  • Create a Feature Branch: Create a new branch for your changes, distinct from the main branch.
  • Implement Changes: Make the necessary code changes or additions to address the issue.
  • Run Tests: Execute any provided tests to ensure your changes do not introduce regressions and function as expected.
  • Commit with Clear Messages: Write concise and descriptive commit messages that explain the purpose of your changes.
  • Push to Your Fork: Push your feature branch to your forked repository on the platform (e.g., GitHub).
  • Open a Pull Request (PR): Create a pull request from your feature branch to the project's main branch, clearly describing your changes and referencing the issue it addresses.
  • Add projects Maintainers to your PR to review your work.
  • Respond to Feedback: Be prepared to address any feedback or requests for changes from project maintainers during the review process.

Community Engagement

  • Polite Communication: Maintain a respectful and professional demeanor when interacting with maintainers and other contributors.
  • Ask Questions: Do not hesitate to ask for clarification or assistance if you encounter difficulties.
  • Stay Engaged: Consider contributing further to the project after your first contribution is merged.