Contributing with Github
Install the Git software
- 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
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 "firstname.lastname@example.org"
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
If you haven't already, create an account in Github
Fork the project
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)
Check out your fork
Here is an example for the dpocock fork
mkdir ~/ws cd ~/ws git clone email@example.com:dpocock/resiprocate.git resiprocate
Create a branch from master
cd resiprocate git branch build-fixes git checkout build-fixes
Make your changes, e.g.
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
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:
and it will send them.
Create a pull request
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
Click the button and add any comments for the reviewers.
Getting the latest code into your local copy
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.