Skip to content

Easy Open Source workflow

So you’ve found an open source project to contribute to but you don’t really know where to start? It can all look pretty daunting but the good news is that it’s just a process of pretty easily repeatable steps; and the idea of this webmaker-bitesize article is to show you those and explain why they’re required.

Assumptions

  1. While the steps I’ll be outlining are easily reproducible across any version control system the code snippets I’ll be proving are assuming that we’re using git.
  2. There are numerous git clients out there but I’m suggesting that using the CLI (command line interface) is the best way to go. I’ve not found any desktop client that makes things easy, or in some cases possible. Let me know in the comments if I’ve overlooked a good one
  3. You’ve already got a repo checked out locally and set an upstream remote to keep in-sync

tl;dr

I’ve written a lot of words with this article where I try and explain what’s going on. In essence the process is this:

  1. git checkout master
  2. git pull upstream master

    git checkout -b branch-name

  3. Do work
  4. git rebase -i HEAD~{number of local commits you made to fix things}
  5. git pull --rebase upstream master
  6. Send pull request
  7. Go through code review
  8. Party

I’m also feeling that this could be a perfect time for a screen-cast…

Getting started

Before you start coding there are a few things you should do in order to make your code easy for the project team to accept.

Fix a real issue

Check the project bug tracker for a bug to fix and assign it to yourself (this will stop anyone else working on it and let people know that you are). If the thing that you want to fix isn’t found then file a bug yourself (follow my article on good bug writing) and assign it to you.

Fix one issue at a time

One problem I’ve found people get frustrated about is when their pull request gets stuck in limbo because while 90% of it is good the remaining 10% is causing issues; the 90% is good to merge and solves a number of issues but can’t be because of the stuff holding it up. You can solve this with a bit of focus and in the same way that filing one issue per bug (and not a mega bug with about 5 different problems in them) makes them easier to resolve in your contributions it makes it easier to land in the project.

Update your local code

Depending on when you checked out the repo things might have changed a little. Out of habit whenever I start work on a new issue I run:


git checkout master
git pull upstream master

This makes sure that you’re on the master branch and have everything up to date – meaning that you should be working on the same code as everyone else in the project.

Work in a branch

git checkout -b branch-name-of-choice

Working in a branch means that you’re always able to update master without worrying about any local changes you might have made to it. This also means that if you need to work on a new bug before finishing an existing one you can just checkout master and create another.

Do the work

At this point you’re ready to work. There is nothing specific to open source projects here and you should work as you normally do. Make sure that you’re:

  • commenting your code,
  • writing tests if they’re needed,
  • not breaking existing tests.

The only thing to look out for is that you’re following the code writing style of the project – if variable names are all in camel-case don’t start naming them with hyphens or underscores, if end line colons are required then don’t go leaving yours out. Hopefully the project has a CONTRIBUTORS.md file containing this information or a style-guide document to follow.

Once you’ve fixed the issue

You’ve done the work and fixed the issue. While you could open the pull request now there are a couple of things you can do to make things easier for yourself.

Send an atomic commit

In your local branch you might have completed the work over a number of different commits. Locally this is fine but to get into master it’s good practice to have just one commit. You’re going to want to do an interactive rebase; this is also sometimes referred to as ‘scrunching up your commits’.

First up see how many commits you’ve done, for this example I’ll assume 3 (one for the initial work and another where you fix stuff you didn’t notice beforehand – something I do all the time!)

Now run:

git rebase -i HEAD~3

This will give you you’re list of commits and a few options. Generally what I do is pick the top commit and fix-up all the remaining ones. If you want to change the commit message use reword (instead of pick) and you can do once the rebase has finished.

A terminal window showing the output from running the interactive rebaseWhat an interactive rebase looks like

Update your branch

Depending on how long the work has taken there is a big chance that something might have been updated in the upstream repo.

git pull --rebase upstream master

Fix any conflicts and once this is complete just re-test your code to make sure it’s all still working as expected.

Send in your pull request

This is done via github. Make sure to reference the bug somehow in the summary or description so people can check that it does what it is supposed to.

Fixing conflicts while rebasing

Up to only recently this used to frustrate me no end. The key part is to not commit things once you’ve fixed the conflicts, just add them and use git rebase --continue. If you commit you’ll start working on a non-existing branch and leave a incomplete rebase – and that really is as confusing as it sounds!

Code review

Be attentive to any comments made and fix them up (remembering to re-run git rebase -i HEAD~2 each time to ensure the atomic commit, you’ll also need to re-push your branch with the changes to git git push -f origin branch-name).

The code review process is one worthy of it’s own article but the main thing to remember is that all the comments will be done for reason, and it’s a conversation so if you’re unsure on anything please do ask questions!

Code is merged

Once you’ve passed review you’re code should be merged in – and you’re now an open source contributor! Follow these steps each time and it’ll soon become a habit and second nature.