Skip to content
This repository has been archived by the owner on Jun 12, 2021. It is now read-only.

Contribute

Jump to bottom
stasm edited this page May 23, 2011 · 18 revisions

We use git flow to manage our branching process. You're encouraged to make use of feature branches for every bug you work on.

Getting Started

To get started, fork the elmo repository, and with your own fork,

git clone git://[email protected]/username/elmo.git
cd elmo
git checkout -b develop origin/develop
git submodule update --init --recursive 
git flow init -d  # answer yes to all defaults

We've created a list of good first bugs which should help you get familiar with the codebase.

If you're new to git, check out the git cheatsheat.

Summary

When you're ready to ask for a review, first commit your changes to the feature branch and then attach the patch of the resulting changeset to the bug. Collect feedback and, if needed, address the review comments in new commits on the feature branch.

When the feature is ready,

  1. squash all commits into a single one,
  2. adjust the commit message to include the bug number and the review,
  3. and merge.

Thanks to this workflow,

  • while you are working on the patch, you see the whole history of your changes on the feature branch,
  • but you merge a single commit onto develop branch, so you don't pollute the log with the automatic merge changesets.

Start a new feature branch

Assume you're working on bug 600000 that is about adding installation docs to the codebase.

git flow feature start 600000-install-docs
# ...write code...
git commit -m "Add the INSTALL file"
git diff develop...HEAD > patch.diff
# ...attach the patch on bugzilla and get review...

# ...address reviewer's comments...
git commit -m "Specify Python version, as per Joe's review"
git diff develop...HEAD > patch.diff
# ...rinse and repeat...

git diff develop...HEAD is a shorthand diff command that let's you see what a merge to develop would introduce given the current HEAD. Read more about it at http://learn.github.com/p/diff.html#what_a_merge_would_introduce.

Note: If your changes include file renaming, generate the diff by running git diff -M develop...HEAD (which stands for git diff --find-renames develop...HEAD). You can specify a similarity threshold if the default doesn't give you satisfying results, e.g. git diff -M70% develop...HEAD. Find out more about this option in git documentation.

Merge your feature branch after an r+

Once you get r+, you will want to:

  • rebase (and squash changesets),
  • adjust the commit message,
  • merge onto develop.

Rebase

# rebase and squash all changesets into a single one...
git flow feature rebase -i 600000-install-docs

Your editor will open. Leave the first changeset as 'pick' (or 'reword'), and 'squash' (or 'fixup') all others.

pick dd9511f Add the INSTALL file
squash bb0fc6e Add the pip/virtualenv step
squash 64a4f42 Add the third installation step, as per Bob's suggestion
squash 84d7d82 Specify Python version, as per Joe's review
squash b377ca6 Add the env creation step

Adjust the commit message

Your editor will open again. Adjust the commit message. The final commit message should include:

  • the bug number
  • short summary of the changes made on the feature branch
  • reviews (e.g. r=stas)
  • (optional) longer description separated by a blank line.

Example:

Bug 600000 - Add installation instructions, r=stas

The installation instructions are in the INSTALL file.

Merge

You are now ready to merge onto develop.

# ...merge and delete the feature branch...
git flow feature finish 600000-install-docs

Note: If the commit message of the rebased changeset still requires changes, you can fix it before or after the merge.

# ...change the commit message if needed...
git commit --amend
Clone this wiki locally