A couple of days ago a friend of mine asked me how he can change some existing Github project. There are quite some materials around covering this topic, but what I give you here is an exact set of steps required to actually perform the change.
By the end of the article, if you stay with me, you will be able to understand how to technically contribute to the Github open-source projects.
Pick an easy task first
My advice here for the newcomers would be to pick some easy tasks first, like fixing the typo in the project documentation.
Since making any change requires following a formal process, the easiest way is to simply be sure as much as possible that our change will be accepted.
Go, spot some issue yourself, or you can even find some already opened issue for that repository that you feel comfortable fixing.
You may already know the project you want to contribute to, and, in case you don't, you can try finding one in the list of last month's trending Github repositories.
Now, after knowing the project we want to contribute to, we can choose one of two available options:
- Contributing via project forking
- Becoming a member of an open-source project
Contributing via project forking
This is a preferred way of contributing to the open-source, especially for the newcomers.
In simple terms, this is a process of:
- Copying (forking) the project in Github website
- Making the desired change in that (copied) repository
- Opening, via Github UI, request to the upstream repository telling the owner that we'd like them to incorporate our change in their repository
Copying (forking) the project on the Github website
Follow the procedure described in this short video:
It's just a matter of navigating to the project on Github and clicking on the fork button.
A very important thing to note is that Github will preserve this information that your repository is a fork of some other repository. This is important for contributing to the upstream repo (explained in a minute).
Making the desired change in your (forked) repository
If it's easy to make the change, the easiest way is to:
- Go to the Github repository (forked in the previous step)
- Create a new feature branch describing the feature in the branch name
- Making the change in this branch (Github UI allows creating, deleting and modifying files)
- Commit the change giving nice commit message
Opening a pull request
Let's jump straight to the following video explaining how to create a simple change and then open a pull request:
In short, you need to navigate to your repository and choose your branch which contains the change you want to integrate to the upstream repository.
On the left-hand side, you can see the upstream repository, the one you forked. Next to it is the branch name you want to contribute to.
On the right-hand side, you can see your repository and the branch containing your contribution.
The pull request is a standard pull request UI, except for the fact that it spans cross repositories, whereas pull requests are generally more frequently occurring within a single repository.
Becoming a member of an open-source project
The second (and harder) way is to become a privileged user for a given project. Currently, there is only an option to invite someone to the repository, meaning that you can't initiate this in any formal way.
You need to find the project contributors and asked them to invite you to the project.
For this to work, the one to give permission needs to rest assured that you are valuable to the project.
I'd avoid doing it this way but rather focus on the forking approach.
Be polite and patient
Now, make sure you understand that:
- People may or may not react promptly to your pull requests
- In general - the more polite you are the entire process of accepting your changes will be easier
- Reviewing pull requests that are not critical might be very slow and there’s not much you can do about it
- For any nontrivial change, be prepared that you’ll have to satisfy the standards defined by project owners, which means longer review time
What to do with the forked repository
Once you forked the repository and made the change you intended, you can either:
- Delete the repository (the upstream repository you forked will not be affected by this)
- Leave it as is, in case you might want to further contribute to it.
One important thing is that if the upstream repository gets updated after you cloned it, you will have to keep it in sync.
This is how you can do it:
Once you clone your forked repository to your local machine, if you go to your project root and issue a command:
git remote show
you will see that your local repo is completely unaware of the upstream repo. You can add another git remote pointing to it:
git remote add upstream git@github.com:Gitara2014/aws-serverless-crud-sample.git
After that you can maintain sync between your and the upstream repo, by pulling changes from both repos and merging changes from the upstream repo to your fork.
Conclusion
Congratulations on further extending your technical knowledge!
Contributing to the open-source is not that complicated, and now that you feel confident doing it, I encourage you to go to Github and find some interesting projects you'd like to support!