Starting out with open source contributions may have a somewhat steep learning curve. Knowing how to contribute and what contributions to make can feel like a barrier for devs that are just starting out.
This article is a detailed reference guide to remember how to setup your local environment and a few suggestions on how to contribute to an open source project.
Setting up your local environment is simple once you understand what each step means. Let's dissect each item of setting up your local development machine. We will use the Rails repository as an example for this walkthrough.
- Fork the project
- Clone your fork
- Add remotes
- Configure the project
- Make changes
- Push to your fork
- Open pull request
- Make requested changes
Forking the project is basically creating your own version of the original repository. In GitHub, this can be done by clicking the fork button on the top right portion of the screen.
After finishing the fork, you will be redirected to your version of the repository. Notice how the repository names are the same, but the organization/user changes (i.e.:
This step is straight forward. Just clone your fork to the development machine.
git clone firstname.lastname@example.org:your_user_name/rails.git
In order to keep your fork up to date, you need to have a way of pulling the changes from the original repository. To be able to do this, you will need to add the original repo as a remote in your clone. Immediately after cloning, check if this is your current remote:
git remote -v # Output origin email@example.com:your_user_name/rails.git (fetch) origin firstname.lastname@example.org:your_user_name/rails.git (push)
Now, let's add the original repository. List your remotes to check if they match.
# The name "rails" after "add" is arbitrary. Pick whatever you prefer # Some people like to call it upstream git remote add rails email@example.com:rails/rails.git git remote -v # Output origin firstname.lastname@example.org:your_user_name/rails.git (fetch) origin email@example.com:your_user_name/rails.git (push) rails firstname.lastname@example.org:rails/rails.git (fetch) rails email@example.com:rails/rails.git (push)
If you have an output similar to this, you are all set. The following git flow can be used to keep the fork up to date. Of course, if you prefer to pull, merge or use any other git commands, you can always do so. Just be mindful of when to use
origin and when to use
git fetch rails # downloads changes from the original repo git rebase rails/master # rebases your branch on top of master git push origin master # updates your fork's master
This step is completely dependant on the project you are working with. Configuring the project means installing libraries, setting up databases, installing programming languages and any other needs the project has. For a Rails project, this could mean simply running
yarn install. The
README.md file is usually the source for project specific instructions.
It's finally time to get coding (Hurray!). Create a new branch, make whatever code changes you have planned and commit. Remember to make sure tests are passing. Here's a quick reference to the git commands.
# Creates a branch called my_new_branch based on whichever branch # you are currently on git checkout -b my_new_branch # Adds modified or new files into git's staging area git add . # or git add path/to/my/file # Commits your changes # Without any arguments, it will open the default EDITOR git commit # or with arguments just pass the message straight away git commit -m "Modify behavior X"
Now that you have your changes committed in your branch, it's time to push. One thing that can be kind of confusing is that you will always push your changes to your own fork (origin) even if you want your commits to eventually make it into the original repo (rails).
So after your branch has all the changes you desired committed, let's push.
# Pushes the branch to origin git push origin my_new_branch
We are ready to open our pull request now. Visit the original repository's homepage on GitHub (in this example it would be https://github.com/rails/rails). Upon visiting, it should prompt you for opening a pull request in the homepage. If this doesn't happen, simply click
new pull request and pick your branch.
The last step before submitting the pull request is to review your own changes and write a descriptive explanation for them. The better you explain what you are trying to accomplish, the easier it will be for others to review it. Try to always answer the following questions:
What are you trying to accomplish?
Why did you decide on this implementation?
Are there any risks on merging these changes?
Is it easy to rollback if something goes wrong?
The maintainers might request changes in the code after reviewing your pull request. If they do so, make the changes, commit and push to your fork's branch again to update the pull request.
Once the changes are approved by the maintainers, they will merge the commits into master and you will have completed your contribution.
There are numerous ways to contribute to an open source project. Here's a small list of ideas.
Provide feedback about the project
Simply opening an issue and writing feedback can be a very valuable contribution. Stuff like "I thought the user experience was confusing for doing this or that" can help provide insight to the maintainers and might influence new features. Don't hold back on suggestions!
Depending on the project, it may require a lot of documentation to get a new user started. Having clear and well written documentation is a fantastic way to attract more people. If you figured how to achieve something and notice it isn't documented, do so.
Fix a bug
If you found a bug while using the project or if there is an open issue reporting a bug, fix it and open a pull request.
Add a new feature
Put together new functionality and propose it on a pull request for the maintainers. For this types of contributions, make sure to clearly state the use case of why adding this is important for the project.
Code quality or performance refactors are also very valuable contributions. It can also assist in understanding the codebase and getting up to speed on how to add new features.
We all use open source in one way or another. It shouldn't be scary to contribute and to be a part of the community. If you want to get started, go for it.
Let me know if I missed something!