Collaborating

Brewtarget

Brewtarget maintains a repository that attempts to follow the standard git branching model. To add a feature to brewtarget, create a fork of its repository into your own private repository. Then, create exactly one branch per feature you want to add. It will be merged back to the brewtarget repository using pull requests.

Git

If you have never used git before, you need to read Understanding Git Conceptually. It is a concise and well-written document about how git operates.

First, please cd to your local brewtarget git repository and run

$ ./setupgit.sh

This script sets up the brewtarget git repository to conform with our policies about the code within.

Next, set up a really useful alias for viewing your repository by placing the following in .git/config.

[alias]
   lg = log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative

Then, git lg will display a nicely-formatted graph of your local repository.

If I don't have a personal fork of the brewtarget repository, I'd make it. Let's say it's at github.com/me/brewtarget.git. To get a working copy on my machine:

git clone http://github.com/me/brewtarget.git ~/brewtarget
cd ~/brewtarget
git remote add upstream http://github.com/brewtarget/brewtarget.git

will copy the repository to my local folder ~/brewtarget and start me out in the develop branch. Never make changes to this branch since it is "owned" by the upstream brewtarget repository. The second command adds the alias upstream which points to the brewtarget repository.

Now, I create exactly one branch per feature that I want to add or bug I wanted to fix. Supposing I have 2 features in mind:

cd ~/brewtarget
git fetch upstream
git branch feature1 upstream/develop
git branch feature2 upstream/develop

This creates 2 branches in my local repository, starting from the upstream develop branch (you should always initialize new branches from upstream/develop and run git fetch upstream before doing so). To start working on feature1:

git checkout feature1

and then modify files until I get tired of working on this feature. At that point:

git commit -a -m 'Some message talking about what I just did.'
git push origin feature1

The first command makes a commit object in the local repository and saves the work. The second uploads those changes back to the origin , which is an alias for the place you cloned from (github.com/me/brewtarget.git ~/brewtarget). Now, you are free to continue working on feature2:

git checkout feature2

This changes the files in your local directory to match the feature2 branch. Now, you can edit, commit, and push just like you did with feature1.

You can also branch from upstream/develop and check it out at the same time with

git checkout -b feature3 upstream/develop

When you are done with your feature1, you might want it merged back upstream. To do this, first bring your branch up-to-date with upstream/develop with a rebase:

git checkout feature1
git fetch upstream
git rebase upstream/develop

This may require you to resolve some conflicts that have occured, though usually they should be trivial. When this is done, push your branch to your personal clone and create a pull request of that branch to upstream/develop.

Pull Requests

GitHub Pull Requests are a mechanism for code review. A pull request is a staging area for others to view your changes and provide feedback. First, take a look at how to write the perfect pull request. At least one other Brewtarget team member other than the author must review each request. The reviewer(s) will inspect the code changes after applying the Under Review tag. The reviewer(s) will then provide comments and give a +1 or -1 comment. If further work is required (as denoted by -1), the author should make the changes and update the request. The process repeats until all the reviewers have given a +1.

When the request is ready, the author should squash all commits onto the current upstream/develop head (example here). The squashed commit should have a commit message with the pull request number in the headline as follows:

PR42: fixes #11 - crashing on doing something normal

This fixes the crashing on doing something normal. I had to fix:
- x
- y
- and z

Please note that once a pull request is created, you should not merge any changes from any other branch into the request branch. This makes merge requests dependent on each other, which can get very messy. You may rebase onto the current upstream/develop, but only if absolutely necessary to complete the change. If changes are required, simply continue work on the request branch independently of your other branches.

Some tools

One of the things I have been having a problem with is remembering what branch I am before I start editing files. I found this for zsh and a port to bash. There are a lot of different canned prompts like these, but I liked the brevity (I do not like my prompt to be 2+ lines long) and the easy customization.

A subversion user's guide to git provides a useful cheat sheet for those used to svn but not so much git.

A very nice guide to conflict resolution, since I seem to get a lot of conflicts, particularly when playing with the UI files. If you are a vim junky like I am, use vimdiff and this guide to explain the display.