Contributing with Github

From reSIProcate
Jump to: navigation, search

Install the Git software[edit]

  • Linux and Mac OS: the git utility is probably already on your system, if not, install it with the package manager (apt-get on Debian/Ubuntu, yum on Fedora). Installing the gitk GUI is also useful for exploring repositories.
  • Windows: see the instructions Quick Windows Git Installation

Set up your Git config[edit]

Git uses your real name and email address as an identifier in every commit.

It is mandatory that you set these in ~/.git/config. If you fail to do so, Git will use guessed values and this is often inconvient and impossible to correct after you send your changes to the server.

git config --global user.name "Daniel Pocock"
git config --global user.email "daniel@pocock.pro"

You can and should override these on individual commits when merging patches that you have manually applied from third parties, e.g. using the --author parameter to the git commit command.

Create a Github account[edit]

If you haven't already, create an account in Github

Fork the project[edit]

Go to https://github.com/resiprocate/resiprocate and click the Fork button at the top right-hand corner of the page.

Github will ask you which organisation you want to put your fork in. Choose your personal page (e.g. mine is https://github.com/dpocock)

01-click-fork.png

Check out your fork[edit]

Here is an example for the dpocock fork

mkdir ~/ws
cd ~/ws
git clone git@github.com:dpocock/resiprocate.git resiprocate

Create a branch from master[edit]

cd resiprocate
git branch build-fixes
git checkout build-fixes

Make your changes, e.g.

vi configure.ac

Now add the file to the change set and commit it (these are two steps in Git):

git add configure.ac
git commit -m 'autotools: fix a typo'

Send changes to server[edit]

Commits are stored on your local disk. They are only sent to the server when you explicitly ask to send them using the git push command.

Send the new build-fixes branch up to the server:

git push -u origin build-fixes

This will remember that you always want to send commits on build-fixes when you push. If you make subsequent commits on the same branch, you can just use:

git push

and it will send them.

Create a pull request[edit]

Go back to Github and look at the page for your fork.

Github should tell you that it sees your recent changes and there should be a button labelled Create pull request

02-create-pull-request.png

Click the button and add any comments for the reviewers.

03-submit-pull-request.png

Getting the latest code into your local copy[edit]

Every now and then, you will want to get the latest code into your working copy.

If you are always creating your local changes on private branches then it is very easy and you will never have to manually merge changes into the master branch.

First, if you are on a private branch and have uncommitted changes, stash them with git stash.

Now, checkout the master branch and pull the latest commits from the official repository, then push the changes to your fork:

git checkout master
git pull https://github.com/resiprocate/resiprocate
git push

Now you could merge the latest master into the private branch where you made changes, for example:

git checkout build-fixes
git merge master

If you are lucky, there are no conflicts and the merge is automatic. If there are conflicts, just follow the instructions to resolve them.