=       git-topic

git-topic is a git command to help with a particular kind of workflow, in which
all work is written by an author, and reviewed by someone else.


=       Requirements

* git-topic has only been tested on debian flavours of linux.  Other unix-like
  environments should work.
* git >= 1.7.1        (older versions may work, sans comment[s] commands)
* ruby >= 1.9.2-rc1   (older versions may work)


=       Workflow
==      Workflow in brief
===     Doing Work

1.      Create a topic branch in the wip namespace.
2.      Do some work.
3.      Rebase to create a nice commit history.
4.      Push to the review namespace.  If the wip branch was pushed (e.g.
        because you work on multiple machines) destroy it on the remote.

1.      Create a local branch from a rejected branch.
2.      Do some work, resolve the reviewer's issues.
3.      go to step 3, above.

===     Reviewing

1.          Create a local branch from a review branch somebody else pushed.
2.          Review their work.
3.  a.i.    Accept; merge (fast-forward) master
    ii.     Destroy the review branch. 
    b.      Reject; add notes and push to the rejected namespace and remove from
            the review namespace.


==      Workflow without git-topic
===     Working on a topic (e.g. feature, or bugfix) foo

    # Create a new branch and switch to it.
    git checkout -b wip/hal/foo

    # do some work, create lots of temporary commits
    # when ready to get the code into master, first update so we're rebasing against
    # the latest code
    git fetch origin

    # rebase against latest code
    git rebase --interactive origin/master

    # when done rebasing so wip/hal/foo now has a nice clean commit history, push to
    # a review branch and destroy the remote wip branch
    git push origin wip/hal/foo:review/hal/foo  :wip/hal/foo

    # alternatively if you never pushed your wip branch to the remote there's no
    # need to destroy it, instead only push your local wip branch as a review branch
    #
    # git push origin wip/hal/foo:review/hal/foo


    # later, after your changes have been merged into master, you can delete your
    # local branch
    #
    # git checkout master
    # git branch -d wip/hal/foo



===     Reviewing a  topic (no proposed changes)

    # update origin
    git fetch origin

    # notice there's a review branch
    git branch -r

    # create a local branch that tracks the remote review branch
    git checkout -b review/djh/bar origin/review/djh/bar

    # examine code and examine the local (proposed) commits
    git log master..

    # when done reviewing, merge into master
    git checkout master
    # This should be a fast-forward merge.  If not, it's because something has been
    # added to master since the rebase
    git merge review/djh/bar
    git branch -d review/djh/bar

    # update the new master and destroy the old review branch
    git push origin master :review/djh/bar



===     Reviewing a topic (proposed changes)

As above, but if, after examining the code you feel some changes are
appropriate, you can either:

====    do them yourself and have the other person review and merge

    # do some changes, then destroy the old review branch and make a new one
    # with the cleaned up code.  Now the owner is changed from djh to hal, so
    # djh must review and merge into master
    git push origin review/djh/bar:review/hal/bar :review/djh/bar

====    do some (or no) changes, but with some TODOs for the original author.

    # do your changes on review/djh/bar

    # then update the remote, moving the branch to rejected, indicating the
    # author has some TODOs left.
    git push origin review/djh/bar:rejected/djh/bar :review/djh/bar

    # when the author has resolved the TODOs they will move the branch back to
    # review/djh/bar


==      Workflow with git-topic
===     Doing Work

    # Work on a (possibly new, possibly rejected) topic
    git topic work-on <topic>

    # done with topic; push it for someone to review
    git topic done [<topic>]


===     Reviewing

    # see if we have any topics to review (or rejected topics to fix up)
    git topic status

    git topic review [<topic>]

    # happy with the review, get it into master
    git topic accept

    # unhappy with the review
    # edit files to add file-specific comments (see git-topic comment --help for
    # details).
   
    # save your file specific comments, and launch an editor to enter general
    # comments about the topic.
    git topic comment

    # push the topic to rejected.
    git topic reject

==      Again, but with aliases

    # first install aliases
    #   add --local if you don't want to update your global aliases
    git topic install-aliases

    # alternatively
    #   git w <topic>
    git work-on <topic>

    # see reviewer's comments
    git comments

    # finished, submit work
    git done


    # does status --prepend so you get git status output as well as git topic
    # status
    git st

    # alternatively
    #   git r <topic>
    git review <topic>

    git accept
    # or
    git comment
    git reject

==      Bash autocompletion

See git-topic --completion-help for details.  In short, you have to do some
manual work, because loading completions as a gem is too slow (see Misc, below,
and ruby issue 3465[1]).

1.  Make sure you source share/completion.bash __before__ sourcing git's standard
    completion.

2.  Copy bin/git-topic-completion to your gem env's default bin dir, overriding
    the generated git-topic-completion.  Otherwise, autocompletion will be too
    slow to be useful.

==      Misc

At present the binary is stupidly slow.  Actually, the binary is not slow, but
all rubygems binaries are slow.  See ruby issue 3465[1].  One way around this is
to modify your PATH so you invoke the binary directly (instead of the rubygem
wrapper).  Alternatively, put up with a 300ms load time until you have a ruby
with the issue fixed.


==      Note on Patches/Pull Requests

1.  Fork the project.
2.  Make your feature addition or bug fix.
3.  Add tests for it. This is important so I don't break it in a
    future version unintentionally.
4.  Commit, do not mess with rakefile, version, or history.  (if you want to
    have your own version, that is fine but bump version in a commit by itself I
    can ignore when I pull)
5.  Send me a pull request. Bonus points for topic branches.

==      Copyright

Copyright © 2010 David J. Hamilton. See LICENSE for details.

==      References

1. http://redmine.ruby-lang.org/issues/show/3465