A few years ago I jumped ship from the Microsoft bubble into the realms of Open Source. It has taken a lot of practice to gain some confidence to make contributions, but the time has finally come.
One obvious hurdle that was always in the way was how to make open source changes. Sure, I could make a Django website or an Ember.JS application - but making contributions to the source code is a whole 'nother beast.
Step 1 - Understand the System
The first thing that everyone needs before making any changes is an awareness of how the change system works (which is what this article is about). Some repositories have specific guidelines, such as Django, which has a nice guide of how to get involved. While Django has more "rules", other repositories will just handle things through GitHub.
Some understanding of git and GitHub are required. You probably have familiarization with git through other projects, but with GitHub you'll need to have an understanding of issues, pull requests, and possibly releases.
Step 2 - Get the Repository
This is the part that I was stuck on for a long time. I was familar with git and GitHub and had no problems working on my own projects, installing pip packages, etc etc. But what do I do to make changes to a repository?
Well my friends, if you have the same questions, you have come to the right place.
First thing to do is fork the repository through GitHub. This part is easy, you'll see a button on a GitHub Repository to fork to a copy on your GitHub account. That will move the repository from https://github.com/django/django.git to https://github.com/awwester/django.git
After that I have a local directory called "Forks". You can call it Repositories, or whatever you damn well please. In that directory I clone the repository from my GitHub fork:
git clone https://github.com/awwester/django.git
At this point you'll have a local copy of the repository on your machine ready to make changes!
Step 3 - Use Repository in local project
Well this is great, the repository is ready to make changes, but how do we use it?
The following instructions are for how to integrate into a python-based project, because at this point, that's all I know. Sorry!
Normally you would install django with
pip install django. When you save your pip packages to your project with
pip freeze > requirements.txt you'll see a line that says
Django==1.8.7 (or whichever version you're on). That is what we're going to change. The line should say
-e /Path/To/My/Repository (in my case it is
At this point you can make changes to the repository and it will be reflected in your project. Pretty cool, right!
Step 4 - Make a Pull Request
So you're all happy making changes and seeing it reflected in your project. Then you decide to make an actual change. You find an issue on GitHub, you let people know you're working on it, and then you fix the bug on your local vesion.
Now what? You create a Pull Request
Ok, we got a little excited, let's take a step back. On your local version of your repository you should create a branch off of master, or whichever is the correct branch to branch from. Normally I name the branch ticket_xxxx where xxxx is the GitHub Issue number. Your changes will be committed onto that branch, and then pushed to your GitHub repo on that same branch.
When the changes are ready to share, you can go to the upstream (main) repository, and create a Pull Request through the GitHub GUI. Sometimes people will give you feedback or changes needed, and sometimes you'll get lucky and everything will be perfect the first time. A maintainer of the project will merge the Pull Request and then your changes will be in master, and will be active in the next release.