Skip to content

Contributing with Github

Jump to bottom
Scott Godin edited this page Jan 29, 2021 · 2 revisions

Table of Contents

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 "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

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 git@github.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. 

 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

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

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.

Clone this wiki locally