[Pkg-jed-commit] r1047 - www

Jörg Sommer jo-guest at alioth.debian.org
Wed Feb 6 16:37:51 UTC 2008


Author: jo-guest
Date: 2008-02-06 16:37:51 +0000 (Wed, 06 Feb 2008)
New Revision: 1047

Modified:
   www/DJG-Guidelines.txt
Log:
git usage guidelines

As we start using git for some packages I've written some hints on how to use
git for packaging and some guideline about the layout.


Modified: www/DJG-Guidelines.txt
===================================================================
--- www/DJG-Guidelines.txt	2008-01-27 13:16:42 UTC (rev 1046)
+++ www/DJG-Guidelines.txt	2008-02-06 16:37:51 UTC (rev 1047)
@@ -188,6 +188,179 @@
      -- Sam Uploader <sam.u at lists.example.org>  Sat, 19 Mar 2005 09:29:18 +0100
 
 
+4. GIT repository
+-----------------
+
+We track in the master branch only the Debian patch, i.e. the contents of
+.diff.gz. Nevertheless, all files should have correct permissions, e.g.
+patches in debian/patches should be executable and all files should be
+world-readonly. This means the top directory should only contain the
+directory debian (beside .git).
+
+Remark: The rational of using dpatch and not git to manage patches is
+  that as long as dpkg do not support git directly, it should be as easy
+  as possible for users to remove or reorder patches or add new patches.
+
+Remark: Tracking only the debian files in the master branch and don't
+  merge in the upstream source makes it easier switch to another VCS and
+  you can see clearly what's the Debian part is.
+
+Additionaly to the master branch, the repository should contain a branch
+“upstream” that contains the upstream source. You should add a branch
+“merged” which is the upstream branch with the master branch. Upon this
+branch you should start a branch “work” where you commit new changes.
+
+      o---o---o---o---M                     master
+       \               \
+    o---o-------o-------o                   merged
+   /           /        |
+  o---o---o---U         |                   upstream
+                         \
+                          W1---W2---W3      work
+
+This looks difficult, it has some advantages:
+• The master and upstream branches contain nothing else.
+• It's possible to publish the work branch and discuss the changes.
+  Later, when these changes are accepted they can be moved to the master
+  branch with rebase and you get a clean master branch.
+
+      o---o---o---o---M---W1---W2---W3      master
+       \               \             \
+    o---o-------o-------o-------------o     merged
+   /           /
+  o---o---o---U                             upstream
+
+The master branch should never be rebased. Git can't handle this.
+
+You might also create feature branches additionally to the work branch,
+e.g a branch to migrate to or from cdbs.
+
+      o---o---o---o---M                     master
+       \               \
+    o---o-------o-------o                   merged
+   /    |      /        |
+  o---o-|-o---U         |                   upstream
+        |                \
+        |                 W1---W2---W3      work
+         \
+          o---o---o                         feature
+
+Start a new Debian version
+--------------------------
+
+If the upstream branch doesn't exist already, you should create it with
+
+    git branch --track upstream origin/upstream
+
+Then checkout the branch, unpack the new upstream version and commit it.
+
+    git checkout upstream
+    rm -r *   # pay attention to keep the .git directory!
+    tar -xf source.tar.gz --strip-components=1
+    git add .
+    git commit -m "Imported upstream version XY"
+
+Now, update the merged branch
+
+    git checkout merged    # add -b to create it
+    git merge upstream
+
+and start the work branch
+
+    git checkout -b work
+
+When you start a new version, the entry in the first commit should look so
+
+    jed-cool (1.2.3-4) UNRELEASED; urgency=low
+
+     -- Sam Uploader <sam.u at lists.example.org>  Thu, 01 Jan 1970 00:00:00 +0000
+
+Do not update the timestamp with every update of the file. Changing the
+timestamp with every commit clutters the diff and might cause problem on
+merging and cherry-picking.
+
+Making changes
+--------------
+
+Keep changes as small as possible and change only one thing per commit.
+Every commit should bring the system from a consistent state into a
+consistent state. If an entry for your change should go into the
+changelog file, include it in the commit. This makes cherry-picking and
+reverting easier.
+
+Before you can commit your changes you must add them to the index with
+“git add <file>” or you use “git commit -a” to include all changed files
+into the commit. With “git add -i” you can select only parts of a file
+for the commit. This is very handy when you do multiple changes to get a
+fully working system and dispense them later on different commits.
+
+To do a commit use “git commit” and give in the first line a short
+summary of the change, leave the second line blank and after this you can
+describe the change more in detail.
+
+Changing commits
+----------------
+
+Sometimes you find mistakes in old commits like you've forgot to put the
+patch name in debian/patches/00list or you forgot to include 00list in
+the commit. With GIT it's possible to change a commit, but this might
+cause problems.
+
+* Fix the last commit
+
+Simply edit the file, add it to the index (git add FILE) and run
+“git commit --amend”
+
+* Fix a patch before the last
+
+Changing a patch in the farer history might cause problems, because it
+uses rebase.(`git rebase problems`_) You should never do this on the
+master branch without telling all other project members before.
+
+1. Checkout the bad commit. This creates a detatched head.
+
+  git checkout COMMIT
+
+2. Edit the file.
+
+  jed FILE
+
+3. Add the file to the index and replace the last commit.
+
+  git add FILE
+  git commit --amend
+
+4. Apply all other changes made in the work branch starting at the
+   current commit.
+
+  git rebase --onto HEAD HEAD@{1} work
+
+Publish the changes
+-------------------
+
+When you finished your work and start the discussion about it you can
+publish your work branch with
+
+  git push origin work:work-YOUR-SIGN
+
+This branch is open for rebasing and every change you can think of. So,
+nobody should start a branch based on this, if he doesn't really know
+what he does.
+
+When the changes are accepted, you should include your work in the master
+branch and publish this:
+
+  git rebase --onto master upstream work
+  git checkout master
+  git reset --hard work
+
+  git checkout merged
+  git merge master
+
+  git branch -d work
+
+  git push
+
 (`view history`_)
 (`view source`_)
 (`PDF version`_)
@@ -195,4 +368,5 @@
 .. _view history: http://svn.debian.org/wsvn/pkg-jed/www/DJG-Guidelines.txt?op=log&rev=0&sc=0&isdir=0
 .. _view source: http://svn.debian.org/wsvn/pkg-jed/www/DJG-Guidelines.txt?op=file&rev=0&sc=0
 .. _PDF version: DJG-Guidelines.pdf
-.. _svn-import-pkg: http://svn.debian.org/wsvn/pkg-jed/utils/svn-import-pkg?op=file&rev=0&sc=0
\ No newline at end of file
+.. _svn-import-pkg: http://svn.debian.org/wsvn/pkg-jed/utils/svn-import-pkg?op=file&rev=0&sc=0
+.. _git rebase problems: http://marc.info/?l=git&m=119943743006341&w=2




More information about the Pkg-jed-commit mailing list