Add HACKING doc with Github workflow notes. #317

Merged
merged 2 commits into from Mar 1, 2014
View
@@ -0,0 +1,145 @@
+Typical Github workflow
+=======================
+
+Git allows you to work in a lot of different work flows. Here is one that
+works well for our environment, if you are not already familiar with git.
+
+To set up the environment, first fork the repository. Once the fork is
+complete, create a local copy and work on a feature branch.
+
+::
+
+ git clone git@github.com:{yourusername}/Bookie.git
+ cd Bookie
+ # Add a second remote to the upstream Bookie repository your fork came from.
+ # This lets you use commands such as `git pull bookieio develop` to update a
+ # branch from the original trunk, as you'll see below.
+ git remote add bookie git@github.com:bookieio/Bookie.git
+ # Create a feature branch to work on.
+ git checkout -b {featureBranchName}
+ # Hacky hacky hacky
+
+
+To push code for review, cleanup the commit history.
+
+::
+
+ # Optional: rebase your commit history into one or more meaningful commits.
+ git rebase -i --autosquash
+ # And push your feature branch up to your fork on Github.
+ git push origin {featureBranchName}
+
+
+In order to submit your code for review, you need to generate a pull request.
+Go to your Github repository and generate a pull request to the `bookie:develop`
+branch.
+
+After review has been signed off on and the test run has updated the pull
+request, a member of the `Bookieio` organization can submit the branch for landing.
+
+Once the code has been landed you can remove your feature branch from both the
+remote and your local fork. Github provides a button to do so in the bottom of
+the pull request, or you can use git to remove the branch. Removing from your
+local fork is listed below.
+
+::
+
+ git push origin :{featureBranchName}
+ # And to remove your local branch
+ git branch -D {featureBranchName}
+
+Before creating another feature branch, make sure you update your fork's code
+by pulling from the original Bookieio repository.
+
+::
+
+ # Using the alias from the Helpful aliases section, update your fork with
+ # the latest code in the Bookie develop branch.
+ git sync-bookie
+
+ # And start your second feature branch.
+ git checkout -b {featureBranch2}
+
+
+Syncing your feature branch with develop (trunk)
+-------------------------------------------------
+
+Time to time you have a feature branch you've been working on for several days
+while other branches have landed in trunk. To make sure you resolve any
+conflicts before submitting your branch, it's often wise to sync your feature
+branch with the latest from develop. You can do this by rebasing your branch
+with develop.
+
+The recommended pattern would be to
+
+::
+
+ # Update your local copy of develop with the latest from the bookie branch.
+ git sync-bookie
+
+ # Then check back out your feature branch and sync it with your new local
+ # develop.
+ git checkout {featureBranch}
+ git sync-trunk
+
+You should see messages for each landed branch getting rebased into your work.
+
+::
+
+ First, rewinding head to replay your work on top of it...
+ Applying: Created local charm new or upgrade inspector.
+ Applying: Refactored local charm upload helpers to support multiple service upgrades
+
+
+Helpful Git tools and aliases
+=============================
+
+Tools
+-----
+
+`Git Remote Branch
+<https://github.com/webmat/git_remote_branch>`_ - A tool to simplify working
+with remote branches (Detailed installation instructions are in their readme).
+
+Aliases
+-------
+
+Git provides a mechanism for creating aliases for complex or multi-step
+commands. These are located in your ``.gitconfig`` file under the
+``[alias]`` section.
+
+If you would like more details on Git aliases, You can find out more
+information here: `How to add Git aliases
+<https://git.wiki.kernel.org/index.php/Aliases>`_
+
+Below are a few helpful aliases we'll refer to in other parts of the
+documentation to make working with the Bookie easier.
+
+::
+
+ ###
+ ### QA a pull request branch on a remote e.g. Bookieio
+ ###
+
+ # Bring down the pull request number from the remote specified.
+ # Note, the remote that the pull request is merging into may not be your
+ # origin (your github fork).
+ fetch-pr = "!f() { git fetch $1 +refs/pull/$2/head:refs/remotes/pr/$2; }; f"
+
+ # Make a branch that merges a pull request into the most recent version of the
+ # trunk (the "Bookieio" remote's develop branch). To do this, it also updates your
+ # local develop branch with the newest code from trunk.
+ # In the example below, "bookie" is the name of your remote, "6" is the pull
+ # request number, and "qa-sticky-headers" is whatever branch name you want
+ # for the pull request.
+ # git qa-pr bookie 6 qa-adding-some-tests
+ qa-pr = "!sh -c 'git checkout develop; git pull $0 develop; git checkout -b $2; git fetch-pr $0 $1; git merge pr/$1'"
+
+ # Update your local develop branch with the latest from the bookie remote.
+ # Then make sure to push that back up to your fork on github to keep
+ # everything in sync.
+ sync-bookie = "!f() { git checkout develop && git pull bookie develop && git push origin develop; }; f"
+
+ # Rebase develop (trunk) into the current feature branch.
+ sync-trunk = rebase develop
+
View
@@ -26,3 +26,8 @@ If you're on Ubuntu, you should be able to get started with:
$ git clone git://github.com/bookieio/Bookie.git
$ cd Bookie && make sysdeps && make install && make run
$ google-chrome (or other browser) http://127.0.0.1:6543
+
+Developing
+-----------
+If you wish to hack on Bookie with the rest of us please check out the
+`HACKING.rst` doc in this tree.