I just handed python-gsw over to the TEOS-10 group. Even though that is probably my dearest project, I do not have the time to be a full time developer anymore. However, I will gladly review Pull Requests (PRs) ;-)

That is why I decide to post a small recipe to help people get started with GitHub PRs.

This post not intended to be a complete guide on how to fork, branch, and prepare a Pull Request. It is just a recipe with a few commands, like a copy-and-paste cheat sheet.

Setting the fork up

The first step is to create a GitHub account, and to configure git. Then you may navigate to

https://github.com/TEOS-10/python-gsw

and fork the code by clicking on the upper right "Fork" button.

After that you may clone your fork using ssh

git clone git@github.com:your_username_here/python-gsw.git

or https

git clone https://github.com/your_username_here/python-gsw.git

I like to use ssh and here is how to setup it up with GitHub. Now type

git remote -v

You should see your forked repository as origin. Before continuing you need to set an upstream repository. You will be able to fetch code from upstream and send PRs there. Let's set the new official repository as upstream:

git remote add upstream https://github.com/TEOS-10/python-gsw.git

Now type git remote -v again and note that you should have both upstream and origin listed. For the upstream I like to use https instead of ssh. The main reason is to avoid pushing directly to it. Hopefully that will be clear in a moment.

Pull Request (PR)

PRs are more than a request to incorporate your code into the upstream repository, they are how developer "talk" and "evolve" ideas. Usually a PR is not merged right away. In fact a PR is the beginning of a discussion. Here is an example of that conversation happens (that is my very first PR to matplotlib).

How to submit a PR? First create a branch on your fork and check the branch out*:

# Use meaningful branch names like "fix_bug_x" or "add_feature_y".
git branch my_awesome_code
git checkout my_awesome_code

Now code away! Create file and add it with git add new_file, modify a file and commit it with git commit my_modified_file. Use git status to see what was modified and git diff my_modified_file to see the differences. Consider using some git aliases** to help with your work flow.

It is good practice to make small increments when modifying a code. Send several small PRs instead of a big one, specially if the modifications are not related to each other. Once you have finished your changes it is time to push your local branch to origin:

git push --set-upstream origin my_awesome_code

That is not the PR yet! You need to open a browser and go to your fork on GitHub, you should see a "Create pull request" button. Click on that, write a meaningful message and let's talk code!

Last comments

After the PR is merge you can delete your branch with git branch -D my_awesome_code and prune remote branches with git remote prune origin. Remember to keep your local copy up-to-date with upstream by issuing git fetch upstream and then git merge upstream/master. (You may use git pull instead, but I will leave as an exercise for you to find what are are the differences and why fetch is preferable to pull.)

That is basically it. But git+GiHub is much more than that! There are plenty of questions on stackoverflow that might help you go a little bit further. Also, take a look at matplotlib's and iris' developers guide.

I hope that this post got you excited to help the python-gsw project.

* Consider making your prompt git aware. If you use bash try http://bl.ocks.org/mikeric/3989635, if you use zshel try the amazing http://ohmyz.sh/

** Here are my aliases:

[alias]
    pull = pull --ff-only
    st = status -s
    ci = commit
    co = checkout
    diff = diff --word-diff
    ll = log --pretty=format:"%C(yellow)%h%Cred%d\\ %Creset%s%Cblue\\ [%cn]" --decorate --numstat
    ls = log --pretty=format:"%C(yellow)%h\\ %ad%Cred%d\\ %Creset%s%Cblue\\ [%cn]" --decorate --date=relative
    filelog = log -u
    la = "!git config -l | grep alias | cut -c 7-"
    grep = grep -Ii