TL:DR; GitHub Issues is an excellent way to find and contribute to open-source projects. Sorry, but you no longer have an excuse not to learn, grow, or contribute. (https://github.com/search?q=label%3A%22good+first+issue%22+language%3AGo+&type=issues)

What Is GitHub

If you’ve never heard of GitHub, check out Programming with Mosh for a 2-minute explanation. For a more in-depth example of using GitHub, you can look at DevOps For Developers’ Introduction to Source Control for DevOps.

GitHub Has Issues

GitHub literally has Issues! There’s a joke in there somewhere, but alas we must save that for another time. As a project owner, there are always more things to get done than there is time.

Enter “GitHub Issues,” an itemized list of labeled work that requires attention.

Issues for your project

What GitHub Issues Do for a Project

GitHub has been rolling out more features to help project creators. Issues, the feature we are focusing on here, helps organize requirements, future work, and facilitates collaboration. It allows project owners to create discrete units of work to move the project along.

Ideally, Issues should communicate the following information:

  • Summary - describing what needs to be accomplished and/or how it will impact the project.
  • Acceptance Criteria - explicit steps that need to be covered for the Issue to be considered done.
  • Notes - any additional information or, if there is a bug, the steps to reproduce the bug.

How GitHub Issues Will Help You Grow

Reviewing available GitHub Issues is a great way to discover projects waiting for a developer. Often, as I work on a passion project, creative juices flowing with All Them Witches cranked up high on my headphones, I realize something needs to be refined, refactored, or implemented. If I stop to work on that, I lose the momentum and can stall out. Using GitHub Issues, I can capture what is needed and return to it when I have the time or, better yet, allow someone else to lend a hand. This is where you come in; by finding my GitHub Issues.

When starting to learn a new project or technology, look for any GitHub Issues with the tag “good first issue.” These may often be relatively easy to fix and are a great entry point for open-source contributions.

Here are some steps to keep in mind as you start working on a GitHub Issue:

  • Set realistic goals. It takes time and effort to become proficient. Easy is relative; completing that first task on a new project can take a significant effort.
  • Be patient. There will be times when you feel frustrated or discouraged; remember that everyone makes mistakes when learning something new.
  • Don’t be afraid to ask for help. You are here to improve a project; the owners will be happy with your initiative. Having said that, remember patience. This is someone’s passion project, and they probably have a day job; therefore, it may take a day or two to respond.

Any Commit Is Welcome

When venturing into the world of open-source software, you will find that communities are happy for all contributions, regardless of size or perceived importance. You may think your efforts are insignificant but do not allow that to stop you.

Many years ago, I was tasked with adding Avro to a streaming project. Working through the documentation, I discovered a spelling error and dutifully filed a Pull Request. Technically, this one character documentation fix makes me an Avro contributor, Whoo Hoo! The real value of this, seemingly insignificant, contribution is to the next developer learning to use Avro; that person doesn’t have to make the same mistake that I did.

Bottom line: if you have to do discovery to use a project, documenting your process is valuable for the next developer.

How to Choose a GitHub Issue Wisely

Our time is precious, which makes choosing a project a decision we must approach carefully. Whether you are new to programming or an old pro, GitHub Issues is a good tool for identifying projects that want help.

Here are some things to consider while looking for a project to contribute to:

The Project Should Interest You

Let’s be honest; you are less likely to finish a GitHub Issue if you’re not interested in the work. Sometimes, you need to push through the suck to grow and learn; working on a subject you believe in helps.

There Should Be Instruction To Help You Start

Once you have a narrowed list of interesting projects, an excellent place to begin is with each project’s README.md file. Take the time to read any files ending in .md, as those files will have more information about different aspects of the project. CONTRIBUTING.md is the usual location for opportunities to contribute.

If you find a project that holds your attention but has no “development” documentation, you’ve found your first commit. Take a first stab at the documentation and ask the project’s owner for clarification or help if you get stuck. This interaction can help you determine if this is worth your time and effort. If not, keep looking.

GitHub Issues Should Be Clearly Defined

The Issue should have a clear goal and definition of done. Rarely does an Issue come with section headers, but the issue should have an identifiable Summary, Acceptance Criteria, and Notes that help guide you to accomplish the acceptance criteria.

If any of this information is missing or unclear, ask for clarification!

You’ve come to contribute code, not define the task or decide what success looks like. Coding is hard enough, so before you commit to expending a great deal of effort on this task, ensure everyone agrees what needs to be done. This will keep you from blindly coding while the owner changes the parameters with every email.

The Project Needs to Be Active

There is nothing like sweating and bleeding all over your keyboard in a music-driven adrenaline haze of coding only to have your emails left unanswered and your pull request ignored.

How do you know if the project is active?

  • How many stars and forks does the project have?
  • When was the last commit?
  • Are there open pull requests?
  • How long have pull requests been open?
  • Are there ongoing discussions in any of the GitHub Issues?
  • Before diving in, comment on the Issue you are taking - do you get a response? How long did it take?

Once You Completed a GitHub Issue

Having turned the music off, gotten your Pull Request approved, and your code is merged into the project, it’s time to focus on the next essential step: promote your work. What to do after is beyond the scope of this post, fortunately, Will Button, of DevOps for Developers, picks up the slack with Contribute to Open Source to gain DevOps experience.