The article I wrote Yesterday with tips to cement your knowledge of programming touched upon collaboration with OSS projects on GitHub.
I realize many people will have some difficulty getting started on that, and one of the roadblocks lays in not knowing how to use git. I want to remove it in a simplistic, yet effective way.
Behold, for this is very, very bad to do on large scale (more on that later), but very effective for jumpstarting small work.
We will use the GitHub website to do all our git-related work. We won’t even need to install git.
Find something you want to hack on. In the previous article (link at the beginning of this article) I wrote of a way to find hackable projects in GitHub.
Step 1: Getting the source
After you’ve found your victim (I recommend you use the repo I set up for this purpose), notice that you have the option to download as a zip.
This will allow you to download a copy of the repository’s actual state (ie: not the history of the project, but it’s current version).
Take this moment to fork the project, too. It’s the button that says “Fork”, located (at the moment this is being written) at the top right corner of the project’s page.
When you download this, make sure you can get the project to work. That is, compile it, and run the tests (if any), and run the executable. If you find any issues, try to find a solution around them. Read the docs. If the docs don’t cover the solution, and you find it, try to put it in the appropriate file.
If for some reason you think the issue is a project issue, then by all means open an issue. But please, be sure. It’s not fun to have a dozen non-issues, but having them may point out a lack in the documentation.
In any case, if you change any source file in this process, including the documentation, pay heed to step 2.
Step 2: Changing a file
Your improvement to the project will need a change of files. Possibly several changes. Now, there’s a limitation with this approach, and it is that you can only register changes (commit) for one file at a time. If you had git installed in your computer, you would not have this limitation. If you need to change several files for one single logical change, please, learn git first, this is a poor substitute.
Carrying on: if a change implies only one file, you’ve hit the jackpot. A change is a concrete, self-contained unit in this case. For instance: you update the documentation by changing the Readme.md file, and that’s all you had to do to “cover scenario X and Y”, as opposed to “changed the file x” and then “change the file Y so that now the project builds properly taking into account the change in file x”, which is not nice.
A feature you want to add may require intermediary steps which don’t leave the project broken; in that case, those are several changes – some may be cosmetic, some may be refactors. Commit each separately. This applies if using git to commit several changed files at once: simultaneously commit all the files that you need to in order to leave the project in a better state than you found it. It’s a good practice, grouping the physical file changes by logical steps (ie: first commit to fix indentation, second commit to refactor some functionality into it’s own function, third commit to include new functionality).
It is important to build the project and run all the pertinent tests every time you will commit.
Oh right, to commit:
Go to your fork of the project, which you can find in your profile, under the tab “Repositories”, and browse for the file you have changed locally. Select it and click the edit button. Now, copy and paste your file into the text area. In the case of Markdown files (like Readme.md), this will be a good place to make the change, because it allows you to preview your changes. Otherwise this is not such a good idea and you should be careful. When you finish, write a comment – a clear one-liner of what you did, and a longer explanation below. The form’s shape will guide you.
Choose the “commit directly to master branch” option, and go to your fork of the project.
Step 3: Do Not Mess Up
Download the project again, make sure you’re downloading your fork of the project. Get the project to work. If it works just like your originally modified copy, you did well. Otherwise, you messed up. Try again. Project maintainers will not like the repeat commits, though, so be extra careful. Or learn how to use git. In case you didn’t mess up, it is time to open a pull request.
Step 4: Open a Pull Request
This one is straightforward: go to the original author’s repository (where you Forked from in the first place), and open a pull request by clicking the green “New Pull Request” button.
You may need to press the link stating “compare across forks”. On the selection screen, make sure the author’s repository is the “base fork”, and yours is the “head fork”. Then press the “Create Pull Request” button.
After the Pull Request is resolved (the author may ask you to do some additional changes on your fork), you can safely delete your fork.
This is a quick and dirty way to work with OSS. It will only be useful for trivial changes, like fixing typos or grammar, or other single-file, easy-to-test, hard-to-mess-up changes.
Please, take some time to learn git. This is a good way to get to know GitHub’s UI, though, so feel free to abuse the repository I created for the purpose. I’ll try and check any issues and pull requests as often as possible. I recommend trying to improve on the meager Readme.md file as practice.