A lot of this guide has been adapted from Kattni Rembor's excellent guide about contributing to CircuitPython Libraries. Check it out here.

Note: There are some places in this guide where the screenshots are of a CircuitPython library. This has only been done when what you would do on the Arduino library is exactly the same as what is being done on the CircuitPython library

Just about all of Adafruit's code and hardware is kept on GitHub - a web service that keeps track of code and files. Since we publish open source hardware and software, this works great to share our designs and also get feedback and improvements from the community. By working together, a large group of people can improve and build upon the body of work that Adafruit has published. You can even find bugs or add new features, and submit those back to us so that everyone can benefit from your effort!

But how do you actually do that? GitHub isn't the easiest site to use, and Git the versioning tool it builds upon can be challenging even for coding experts.

This guide aims to not only show you where to start, but provide you with the entire contribution path, beginning to end. I'll be using Arduino as our example as I have a well-established workflow.

This guide assumes you already have a GitHub account and have installed Git. You're ready to contribute code. Perhaps you've found an issue with an Arduino library. It doesn't currently work properly, and you think you know how to fix it! Now, where do you start?

This guide will walk through all of the steps during the contribution process. You'll learn how to fork and clone a project repository, create a working branch, and commit and push your changes. You'll find out how to create a pull request, and progress through the review process including the conversation and work surrounding a change request. It explains what's involved with giving a review, which is another excellent way you can contribute to a project.

Some of this may sound complicated and confusing. The guide intends to change that. However, if you find that you're still confused while going through the guide - don't worry!  GitHub is hard to explain, and if you have suggestions on how to improve this guide, please feel free to tell us where things get confusing or could be clearer. You can click the feedback link found on the left of the guide, or find us Discord in the #general channel. We'd love to hear from you!

All of the terms introduced in this guide are explained as you are introduced to them, and are also defined in the Glossary found at the end of the guide. If you're ever unsure about a term, feel free to look it up there.

First, you need to make sure you're ready to get started with this guide.

Requirements

Before starting this guide, there are a number of steps found in An Introduction to Collaborating with Version Control that you must complete. You must have Git installed and setup on your computer. You must have a GitHub account. You need to have some familiarity with the command line or be ready to learn. This guide uses a terminal program to interact with Git locally (on your computer).

Expectations

Be aware that this guide has a very specific goal. It is designed to provide you with a complete open source project contribution workflow, beginning with forking the original project GitHub repository.

This guide will not help you with your initial setup of Git or creating your GitHub account. There is no information about troubleshooting issues with your Git setup or configuration. It will not explain how Git and GitHub work. Much of this is covered in An Introduction to Collaborating with Version Control. Further information is likely available through the Git documentation or the GitHub documentation.

The workflow outlined in this guide should apply to any open source project. However, it's always a good idea to check with the project's maintainers to make sure that you're working within their guidelines.

Let's get started!