Initial Linux ZFS GIT Repo

1 files changed, 162 insertions, 0 deletions

diff --git a/GIT b/GIT
new file mode 100644
index 000000000..578e7316b
--- /dev/null
+++ b/GIT
@@ -0,0 +1,162 @@
+=========================== WHY USE GIT+TOPGIT? ==========================
+
+Three major concerns were on our mind when setting up this project.
+
+  o First we needed to structure the project in such a way that it would be
+    easy to rebase all of our changes on the latest official ZFS release
+    from Sun.  We absolutely need to be able to benefit from the upstream
+    improvements and not get locked in to an old version of the code base.
+
+  o Secondly, we wanted to be able to easily manage our changes in terms
+    of a patch stack.  This allows us to easily isolate specific changes
+    and push them upstream for inclusion.  It also allows us to easily
+    update or drop specific changes based on what occurs upstream.
+
+  o Thirdly we needed our DVCS to be integrated with the management of this
+    patch stack.  We have tried other methods in the past such as SVN+Quilt
+    but have found managing the patch stack becomes cumbersome.  By using
+    Git+TopGit to more tightly integrate our patch stack in to the repo
+    we expect several benefits.  One of the most important will be the
+    ability to easily work on the patch stack with a distributed developer
+    team, additionally the repo can track patch history, and we can utilize
+    Git to merge patches and resolve conflicts.
+
+TopGit is designed to specifically address these concerns by providing 
+tools to simplify the handling of large numbers of interdependent topic 
+branches.  When using a TopGit aware repo every topic branch represents
+a 'patch' and that branch references its dependent branches.  The union
+of all these branches is your final source base.
+
+========================= SETTING UP GIT+TOPGIT ==========================
+
+First off you need to install a Git package on your system.  For my
+purposes I have been working on a RHEL5 system with git version 1.5.4.5
+installed and it has been working well.  You will also need to go get
+the latest version of TopGit which likely is not packaged nicely so you
+will need to build it from source.  You can use Git to clone TopGit
+from the official site here and your all set:
+
+        > git clone http://repo.or.cz/w/topgit.git
+        > make
+        > make install    # Default installs to $(HOME)
+
+========================== TOPGIT AND ZFS ================================
+
+One you have Git and TopGit installed you will want to clone a copy of
+the Linux ZFS repo.  While this project does not yet have a public home
+it hopefully will some day.  In the meanwhile if you have VPN access to
+LLNL you can clone the latest official repo here.  Cloning a TopGit
+controlled repo is very similar to cloning a normal Git repo, but you
+need to remember to use 'tg remote' to populate all topic branches.
+
+        > git clone http://eris.llnl.gov/git/zfs.git zfs
+        > cd zfs
+        > tg remote --populate origin
+
+Now that you have the Linux ZFS repo the first thing you will probably 
+want to do is have a look at all the topic branches.  TopGit provides
+a summary command which shows all the branches and a brief summary for
+each branch obtained from the .topmsg files.
+
+        > tg summary
+ 0      t/LAST                          [PATCH] LAST
+        t/feature-commit-cb             [PATCH] zfs commit callbacks
+        t/fix-clock-wrap                [PATCH] fix clock wrap
+        t/fix-dnode-cons                [PATCH] fix dnode constructor
+        ...
+
+By convention all TopGit branches are prefixed with 't/', and the Linux
+ZFS repo also introduces the convention that the top most development 
+branch be called 't/LAST".  This provides a consistent label to be used
+when you need to reference the branch which contains the union of all 
+topic branches.
+
+One thing you may also notice about the 'tg summary' command is it does
+not show the branches in dependent order.  While this project only expresses
+a single dependency per branch TopGit implements dependencies as a DAC just
+like Git.  To see the dependencies you will need to use the --graphviz
+option and pipe the result to dot for display.  The following command while
+long works fairly well for me.  Longer term it would be nice to update this
+option to use a preferred config options stored in the repo if they exist.
+
+        > tg summary --graphviz | dot -Txlib -Nfontsize=8 -Eminlen=0.01 \
+        -Grankdir=LR -Nheight=0.3 -Nwidth=2 -Nfixedsize=true
+
+========================= UPDATING A TOPIC BRANCH ========================
+
+Updating a topic branch in TopGit is a pretty straight forward but there
+are a few rules you need to be aware of.  The basic process involves 
+checking out the relevant topic branch where the changes need to be made,
+making the changes, committing the changes to the branch and then merging
+those changes in to dependent branches.  TopGit provides some tools to make
+this pretty easy, although it may be a little sluggish.  Here is an example:
+
+        > git checkout t/feature-commit-cb  # Checkout the proper branch
+        > ...update branch...               # Update the branch
+        > git commit -a                     # Commit your changes
+        > git checkout t/LAST               # Checkout the LAST branch
+        > tg update                         # Recursively merge in new branch
+
+Assuming you change does not introduce any conflicts your done.  All branches
+were dependent on your change will have had the changed merged in.  If your
+change introduced a conflict you will need to resolve the conflict and then
+continue on with the update.
+
+========================== ADDING A TOPIC BRANCH =========================
+
+Adding a topic branch in TopGit is a little more complicated.  When adding
+a new branch to the end of the patch graph things are pretty easy and TopGit
+does all the work.  However, I expect out common case to be adding patches
+to the middle of the graph.  TopGit will allow you to do this but you must
+be careful to manually update the dependency information in the .topdeps
+file.
+
+        > git co t/existing-topic-branch    # Checkout the branch to add after
+        > tg create t/new-topic-branch      # Create a new topic branch
+        > ...update .topmsg...              # Update the branch message
+        > ...create patch...                # Update with your changes
+        > git commit -a                     # Commit your changes
+        > git co t/dependent-topic-branch   # Checkout dependent branch
+        > ...update .topdeps...             # Manually update dependencies
+        > git commit -a                     # Commit your changes
+        > tg update                         # TopGit update
+        > git checkout t/LAST               # Checkout the LAST branch
+        > tg update                         # Recursively merge in new branch
+
+========================= REMOVING A TOPIC BRANCH ========================
+
+Removing a topic branch in TopGit is also currently not very easy.  To remove
+a dependent branch the basic process is to commit a patch which reverts all
+changes on the branch.  Then that reversion must be merged in to all dependent
+branches, the dependencies manually updated and finally the branch removed.
+If the branch is not empty you will not be able to remove it.
+
+        > git co t/del-topic-branch         # Checkout the branch to delete
+        > tg patch | patch -R -p1           # Revert all branch changes
+        > git commit -a                     # Commit your changes
+        > git checkout t/LAST               # Checkout the LAST branch
+        > tg update                         # Recursively merge revert
+        > git co t/dependent-topic-branch   # Checkout dependent branch
+        > ...update .topdeps...             # Manually update dependencies
+        > git commit -a                     # Commit your changes
+        > tg delete t/del-topic-branch      # Delete empty topic branch
+
+============================ TOPGIT TODO =================================
+
+TopGit is still a young package which seems to be under active development
+by its author.  It provides the minimum set of commands needed but there
+are clearly areas which simply have not yet been implemented.  My short
+list of features includes:
+
+  o 'tg summary --deps', option to display a text version of the topic
+    branch dependency DAC.
+
+  o 'tg depend list', list all topic branch dependencies.
+
+  o 'tg depend delete', cleanly remove a topic branch dependency.
+
+  o 'tg create', cleanly insert a topic branch in the middle
+    of the graph and properly take care updating all dependencies.
+
+  o 'tg delete', cleanly delete a topic branch in the middle
+    of the graph and properly take care updating all dependencies.