Contribute to open-source projects is one of the coolest things in the development area. I also remember, that some years ago, the topic of one edition of FEMUG was exactly this: the contribution in open source projects.
It’s common to be ashamed to contribute to some project, and one of the reasons for it is because you don’t think you have something to contribute. And that’s the point: you can start with anything: a simple revision of code or even a translation.
As you get used to contributing, the process starts to be simple. But for a person who will contribute for the first time, some parts could be confusing.
A simple step by step could be something like that:
- Fork of the project to your Github user.
- Clone of the project forked in your machine.
- Your magic contribution.
- Updating your project version with the original project.
- Send your commits to your GitHub.
- Open a pull request to the original project.
Believe it: doing is easier than writing. Step four was the most confusing for me. And that’s why I decided to show you here.
The upstream guy
Let’s suppose that we forked the project 2017-is-awesome to our GitHub user account. So, at this moment, the original project and your fork are at the same point and equal.
So, we start to make many changes in our version of the project, and we commit them. Simultaneously, you realize that the original project merged a pull request. Now, the projects aren’t equal: actually, they have a lot of differences.
- Your local project has all your changes.
- The original project has new changes from the pull request merged.
If you send your changes to GitHub and try to open a pull request, you will realize that it wouldn’t be possible. To do that, we have updated our local project with the original; that’s when the upstream will help us.
Let’s say you are contributing to my simple blog (the code is old!). We add a remote based on the original version of the blog:
After that, we have to update the upstream:
$ git fetch upstream
With the upstream updated, we have to
merge/rebase our local version (supposing you’re on the
Now, if you want to update your Github repository with your local repository before making your changes and commit them, we do:
And that’s it! Our local project is synchronized and updated with the original version, and if you send the changes to GitHub, the pull request will be enabled.