Our tips and tricks for contributing to open source software on GitHub
This semester, we interned as contributors to the Earth Lab’s package EarthPy, which is an open source package that makes it easier to plot and manipulate spatial data in Python. During our time working on EarthPy, things were always updating and changing. At first, it all seemed a bit overwhelming...
But, as we have worked more as developers of an open source Python package, we have learned a lot of the ins and outs of the workflow.
In this post, we go over how to:
- Fork a repository
- Make a branch of your fork
- Add changes you’ve made
- Commit those changes
- Push your changes to your GitHub account
- Create a pull request
So, come follow us on our yellow brick road leading to your successful contributions to GitHub.
Forking and branching and bears, oh my!
Forks and branches are essential ways to not mess up other people's code. Once you have made a fork of your desired repository, the next step is to make a branch within your fork. Branches are basically different versions of the same code document (called a script). If you create two branches, and you make a change to one, the change will not appear on the other branch you have.
When you start working on a script, your repository is automatically set to the master branch of the repository. This means that it is your original copy of the script, which you forked from the master branch of the package you are editing. When making changes, it is best practice not to edit on the master branch, but instead to make a new branch to make your changes in.
Here are some helpful command line commands to use when creating and switching between your branches:
Create a branch: git checkout -b
This command will create a new branch for you to edit without messing up your master branch.
Switch branches: git checkout
If you have unstaged changes (changes you haven’t staged using git add yet) on a branch, it will not allow you to switch. To switch, either use git add to stage all of your changes. if you don’t want to keep the changes, you can use the command:
Clear unadded changes: git checkout
The file path will be the file that you want to overwrite.
View list of current branches: git branch
Ding, dong, it’s time to make an add!
Git add stages changes made in your local directory on your computer. This means that when you run git add on a file, the changes you have made on the file will be included in your next commit. This website breaks down git add in much further detail. Essentially, we think of git add as a save function. When you’ve made changes you don’t want to lose, make sure you add them to your staging area with git add.
View which changes have and have not been added: git status
This command will show you which files are in the staging area and which ones have yet to be added.
Add a file: git add
It is best practice to add each file that you have made changes to individually (using the command above) instead of using the command git add * (which adds every file that has had changes made to it into your repository). This will prevent you from accidentally adding unintended files to a pull request.
What makes a king from a peasant? Courage!
What makes a staged change permanent? Commit!
Whereas git add will stage the changes made in your repository, git commit will commit the changes (shocker) to a snapshot. This page does a great job of explaining commits in detail, but to summarize, a commit captures your project as it is at the time of the commit. All the changes you made with git add will be stored in a commit. If you commit changes, then mess up your script, you can always go back to your last commit. Think of it as a more permanent save, for when you’re happy with how your script looks and don’t want to lose any of the progress made.
Commit a previous added change: git commit -m ‘Your very detailed description of the changes you made here’
For every commit you make, make sure to document the changes made in the commit message. Developers and collaborators do not want to search through your script to find every little edit, so make sure to describe them well in the commit message.
We’re off to make a pull request!
Pushing and pulling a repository is how to get your changes to the eyes of the developer. Once all the changes you want to make have been successfully committed, you have to push the changes.
Push changes to your GitHub account fork: git push origin
Pushing your commits will send all your commits from your local machine to your copy of the repository you’re editing on GitHub.
After your changes are on your fork, you are now ready to make a pull request to the repository you wish to edit. You are requesting that the owner of that repository pulls down the changes you made (hence the name pull request).
- Go to the main GitHub page of the repository you are working on (not your repository!), make a pull request, and pull from the branch you were editing. NOTE: GitHub will tell you if the branch can merge automatically or not. If not, look over your edits again and see where the issues lie.
- Make sure that your pull requests:
- Are specific (not too many different types of changes)
- Have a descriptive title
- Include a comment explaining all the changes you made and why you made them
- If you opened an issue for the changes first, make sure to link the pull request in the issue you made.
Source: Clipart Library
Now, you will be waiting for the developer to suggest any changes, and then they will (hopefully) merge your changes into their package! You’re now on your way to become a great and powerful open source software contributor, too!