This document describes the common workflow for using git version control to work on a new issue/feature and contribute it back to the code base. It is meant to be oriented towards those unfamiliar with git.

Note: it is assumed git is already installed, and that you have cloned the repository onto your computer otherwise see the README.

Here are a few beginner-friendly resources to learn about git:

• Git and Github for Poets
• Atlassian

What you should have

After cloning, you should have all the source files for this project within a directory called 'rocks' on your computer in the directory where you performed the clone.

Go into the directory and check that it is indeed a git repository, meaning that files in this directory are prone to being tracked by git.

$ cd rocks/
$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

Look at the git branches

$ git branch -a
* master
  remotes/origin/dev
  remotes/origin/master
<possibly other branches>

The local branch you are currently on is marked with *, the branches that are on github are prepended with origin/ along with origin/master and origin/dev you might also have some other branches (omitting -a will only show local branches). This is a useful command if you are ever wondering what branch you are currently on/what branches exist.

Significance of Branches

• master - stable production version of the application that clients are intended to use. Only the dev branch should ever be merged into master to keep from introducing bugs into the main operable version of the application
• dev - development branch that changes are made to. When working on a new issue, branches should be made off of the dev branch and then merged back into dev

Working on an Issue

Suppose you pick up an issue (ie. #12). The following are the general steps to follow for working on adding your changes on your local git repository and then pushing them up to github.

Making a New Branch

Prior to making a new branch make sure that you are on the dev branch:

$ git checkout dev
Branch 'dev' set up to track remote branch 'dev' from 'origin'.
Switched to a new branch 'dev'

This tells us that a new local branch has been created that is linked to the github branch 'dev'. If the dev branch already existed it is a good idea to make sure that it contains the most recent changes on the github dev branch. To pull in these changes from github:

$ git pull
Already up to date.

Git might tell you that your local branch is already up to date with the remote (github) branch or it might go ahead and merge in the changes from github into your local branch.

To work on the new issue, create a dedicated branch for it off of the dev branch and switch over to that branch, you can call the branch something appropriate (corresponding to the issue) and prefix it with the issue number (note: branch names cannot contain spaces):

$ git checkout -b 12-create-wiki-outline
Switched to a new branch '12-create-wiki-outline'

Create Corresponding Upstream Branch

It is a good idea to make your branch and changes within it to be visible to other contributors on GitHub, to create a branch on github linked to your new local branch do:

$ git push -u origin 12-create-wiki-outline
Switched to a new branch '12-create-wiki-outline'
Total 0 (delta 0), reused 0 (delta 0)
<some other info>
 * [new branch]      12-create-wiki-outline -> 12-create-wiki-outline

Committing Changes to Code

Now you can proceed to make the necessary changes in the code on your new feature branch. When you have made a unit of work and feel you want to register those changes in a commit...

First, check the status to see the files that have been changed:

$ git status

Then, add (all) altered files to the git staging area:

$ git add -A

Make a commit with a short and descriptive message:

$ git commit -m "overview of git process"

Occasionally, it is a good idea to push your local branch changes up to github. If you have already set the upstream branch you can simply do:

$ git push

Merging In Upstream Changes

After you are done implementing your feature, and before making a pull request it is good to incorporate the other changes made to the upstream dev while you were working on your issue. One strategy to do this is to merge the changes from the github dev branch into your local feature branch (12-create-wiki-outline):

$ git pull origin dev
From github.com:VasilyF/rocks
 * branch            dev        -> FETCH_HEAD
Already up to date.

Hopefully, changes can be merged seamlessly by git, however sometimes there will be merge conflicts and git will tell you to resolve the conflicts and then make a commit. This is usually easier to do with an IDE. If ever you encounter a merge conflict and want to abort:

$ git merge --abort

Make sure after the merge that you check that your feature still works as intended.

Making a Pull Request

Make sure that the latest version of your feature branch is pushed to github:

$ git push

Then, go on github, in the Pull requests tab select new pull request select the base branch as 'dev' and the compare branch as your feature branch (note: do not make a pull request directly into master). In the pull request description add closes #12 with the issue number that you have been working on. This will trigger github to automatically delete the upstream branch once changes have been merged in. Conventionally feature branches aren't kept around after their changes have been incorporated - this could also be done manually.

You would have to wait for approval from a reviewer before being able to merge your changes. Once changes are merged and the upstream branch is deleted you can get rid of the reference to the upstream branch on your local machine (origin/12-create-wiki-outline):

$ git fetch --prune
From github.com:VasilyF/rocks
 - [deleted]         (none)     -> origin/12-create-wiki-outline

You may also delete the feature branch once you are done with it:

$ git checkout dev
Switched to branch 'dev'
Your branch is up to date with 'origin/dev'.
$ git branch -d 12-create-wiki-outline
Deleted branch 12-create-wiki-outline