[Pkg-jed-commit] r1109 - www
Jörg Sommer
jo-guest at alioth.debian.org
Sun Apr 27 11:50:42 UTC 2008
Author: jo-guest
Date: 2008-04-27 11:50:41 +0000 (Sun, 27 Apr 2008)
New Revision: 1109
Modified:
www/DJG-Guidelines.txt
Log:
New policy for GIT repositories
I've changed my mind about the way to work in GIT repositories. I don't see a
reason why we should not merge the upstream and the Debian package source.
It's really easy to split them (rebase and remove all merges), when we switch
to a different version control system.
I've used this maintainance style in my repository for slrn [1] for some weeks
and I can say it has real advantages. You don't have to use rebase. You can do
merges and similar things.
[1] http://git.debian.org/?p=users/jo-guest/slrn.git
Modified: www/DJG-Guidelines.txt
===================================================================
--- www/DJG-Guidelines.txt 2008-04-22 13:46:58 UTC (rev 1108)
+++ www/DJG-Guidelines.txt 2008-04-27 11:50:41 UTC (rev 1109)
@@ -191,176 +191,216 @@
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).
+In the GIT repositories we track in the branch “upstream” the upstream
+source and in the branch “master” we track the package development. For
+this we merge in the upstream branch on a regular basis.
-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.
+ +---o---D---o---o---o---E---+---o---o---F master
+ / /
+ U---o---o-----------o---o---V upstream
-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.
+ U and V are upstream releases, D, E and F are Debian releases and the +
+ are merges of the upstream branch in the master branch.
-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::
+This way you can checkout the master branch and build the current version
+or start hacking the source.
- o---o---o---o---M master
- \ \
- o---o-------o-------o merged
- / / |
- o---o---o---U | upstream
- \
- W1---W2---W3 work
+Patches to the upstream source must still be dpatches (or anything
+similar) to make the Debian source package as much as useful. With
+dpatches it's easy to see which changes belong together and it's easy to
+disable some changes. The command “git diff --stat upstream..master” must
+only list files in the subdirectory “debian.”
-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.
+4.1 One Debian release cycle
+----------------------------
-Later, when these changes are accepted they can be moved to the master
-branch with rebase and you get a clean master branch::
+Make sure you have the most up to date files with
- o---o---o---o---M---W1---W2---W3 master
- \ \ \
- o---o-------o-------o-------------o merged
- / /
- o---o---o---U upstream
+ git fetch (for Debian sources)
+ git svn fetch (for upstream sources, if upstream uses SVN)
-The master branch should never be rebased. Git can't handle this.
+You should checkout your master branch [1] and import the last changes
+[2] from the central GIT repository by merging. This should result in a
+fast forward merge. Otherwise something is broken. You should ask for
+help on the mailinglist or throw your changes away [3].
-You might also create feature branches additionally to the work branch,
-e.g a branch to migrate to or from cdbs::
+ git checkout master [1]
+ git merge origin/master [2]
+ git reset --hard origin/master [3]
- o---o---o---o---M master
- \ \
- o---o-------o-------o merged
- / | / |
- o---o-|-o---U | upstream
- | \
- | W1---W2---W3 work
- \
- o---o---o feature
+Now, you have two options: Start a new Debian version, e.g. 1.2-2, or
+import the recent upstream changes and start a new version, e.g. 1.3-1.
-Start a new Debian version
---------------------------
+4.1.1 The beginning
+-------------------
-If the upstream branch doesn't exist already, you should create it with
+When you start a new version, you have to merge the current upstream
+source into the master branch.
- git branch --track upstream origin/upstream
+ git merge upstream
-Then checkout the branch, unpack the new upstream version and commit it.
+Now you are here:
- 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"
+ +---o---D---+ master
+ / /
+ U---o---o---V upstream
-Now, update the merged branch
+The first commit in the new cycle must be a change of the file
+debian/changelog that starts a new Debian version, regardless if it a new
+Debian version or a new upstream version. Edit the file [1], add it to the
+GIT index [2] and make the commit [3].
- git checkout merged # add -b to create it
- git merge upstream
+ xjed debian/changelog [1]
+ git add debian/changelog [2]
+ git commit -m "Start a new version" [3]
-and start the work branch
+The commit should look similar to this
- git checkout -b work
+% git show
+commit ca731f5f39b5b8982a8b38d04b569c1fedf9c45b
+Author: Jörg Sommer <joerg at alea.gnuu.de>
+Date: Sat Apr 26 10:56:20 2008 +0200
-When you start a new version, the entry in the first commit should look so
+ Start a new version
- jed-cool (1.2.3-4) UNRELEASED; urgency=low
+diff --git a/debian/changelog b/debian/changelog
+index f1ccf3b..1f95cae 100644
+--- a/debian/changelog
++++ b/debian/changelog
+@@ -1,3 +1,10 @@
++slrn (0.9.9~pre102-1) UNRELEASED; urgency=low
++
++ * This packages is based on the svn snapshot from
++ https://slrn.svn.sourceforge.net/svnroot/slrn/trunk
++
++ -- Jörg Sommer <joerg at alea.gnuu.de> Thu, 01 Jan 1970 00:00:00 +0000
++
+ slrn (0.9.9~pre99-1) unstable; urgency=high
+
+ * This packages is based on the svn snapshot from
- -- Sam Uploader <sam.u at lists.example.org> Thu, 01 Jan 1970 00:00:00 +0000
+Now, you should start a new branch for the changes you want to do. Name
+it work-$YOUR_SIGN.
-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.
+ git checkout -b work-$ME
-Making changes
---------------
+Then you should try to build the package and if it fails, you should fix
+this, e.g. update the dpatches.
-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.
+4.1.2 Making changes
+--------------------
-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.
+After you brought the package in shape, you should start making other
+changes. But keep the following commit policy in mind:
+· The package must build after every commit—except of the first few
+ commits of a new cycle needed to bring the package in shape.
-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.
+· Every commit should change only one thing. Don't so summary commits.
+ GIT is a distributed VCS and you can commit every time. It's not SVN!
-Changing commits
-----------------
+· Do all changes needed for a change, e.g. update the debian/changelog,
+ if necessary, update debian/patches/00list and so on. Ask yourself the
+ question: “If my change gets reverted, is it enough to revert this
+ patch?”
-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.
+· Describe in the commit message, what you want to do and why you want to
+ do it. You have much more space in the commit message than in the
+ Debian changelog. You can put statistics there or explain design
+ decisions.
-* Fix the last commit
+· Don't update the timestamp in the changelog file. Changing the
+ timestamp with every commit clutters the diff and might cause problem
+ on merging and cherry-picking.
-Simply edit the file, add it to the index (git add FILE) and run
-"git commit --amend"
+To make a commit you must add the changed files to the GIT index. You can
+use add whole files [1] or only parts [2]. After this you can view the
+changes [3] and commit them [4]. You can also combine the steps [1] and
+[4] to [5] or [2] an [4] to [6].
-* Fix a patch before the last
+ git add debian/rules [1]
+ git add -i [2]
+ git diff --cached [3]
+ git commit [4]
+ git commit debian/rules [5] = [1] + [4]
+ git commit --interactive [6] = [2] + [4]
-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.
+4.1.3 Fixing commits
+--------------------
-1. Checkout the bad commit. This creates a detatched head::
+The history shouldn't look like this:
- git checkout COMMIT
+· dpatch to support something
+· sorry, I forgot the 00list file, here is it
+· make funny stuff
+· changelog entry for something above
+· improve spelling of funny stuff
-2. Edit the file::
+GIT gives you the tools to fix the history of your branch
+“work-$YOUR_SIGN.” Don't do this in the branch “master!”
- jed FILE
+You can change the last commit with the option --amend [1] or you can use
+rebase [2] to make changes like joining, reordering, removing and editing
+of commits.
-3. Add the file to the index and replace the last commit::
+ git commit --amend [1]
+ git rebase -i HEAD~10 [2]
- git add FILE
- git commit --amend
+4.1.4 Publishing your changes
+-----------------------------
-4. Apply all other changes made in the work branch starting at the
- current commit::
+You don't have to publish every single commit. You can publish many
+commits at a time and there can be days between the commit and the
+publishing. You have enough time to think about what you have done and
+maybe change it!
- git rebase --onto HEAD HEAD@{1} work
+After you have done your changes, you should publish them by running
-Publish the changes
--------------------
+ git push
-When you finished your work and start the discussion about it you can
-publish your work branch with::
+If you used rebase you must use the option --force.
- git push origin work:work-YOUR-SIGN
+4.1.5 Closing the development cycle
+-----------------------------------
-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.
+After all is in shape and the changes are reviewed by the other team
+members, someone should step up and make the release. He should merge [2]
+missing commits in the master branch [1] and do the final commit by
+updating the Debian changelog [2] and add a tag [3]. After this is
-When the changes are accepted, you should include your work in the master
-branch and publish this::
+ git checkout master [1]
+ git merge work-$X [2]
+ git commit debian/changelog [3]
+ git tag 1.3-1 [4]
- git rebase --onto master upstream work
- git checkout master
- git reset --hard work
+The final commit should look like this one:
- git checkout merged
- git merge master
+commit 1c95c225679ff863d29d21f50b6b1b0fe38a544f
+Author: Jörg Sommer <joerg at alea.gnuu.de>
+Date: Sat Apr 26 16:22:34 2008 +0200
- git branch -d work
+ Release of 0.9.9~pre102-1
- git push
+diff --git a/debian/changelog b/debian/changelog
+index 591c5c4..d4e5168 100644
+--- a/debian/changelog
++++ b/debian/changelog
+@@ -1,4 +1,4 @@
+-slrn (0.9.9~pre102-1) UNRELEASED; urgency=low
++slrn (0.9.9~pre102-1) unstable; urgency=low
+
+ * This packages is based on the svn snapshot from
+ https://slrn.svn.sourceforge.net/svnroot/slrn/trunk
+@@ -40,7 +40,9 @@ slrn (0.9.9~pre102-1) UNRELEASED; urgency=low
+ * Dropped the dpatch 206_branding, because I don't see what's the value
+ of this patch except for fun.
+
+- -- Jörg Sommer <joerg at alea.gnuu.de> Thu, 01 Jan 1970 00:00:00 +0000
++ * Upload sponsored by Norbert Tretkowski
++
++ -- Jörg Sommer <joerg at alea.gnuu.de> Sat, 26 Apr 2008 16:19:22 +0200
+
+ slrn (0.9.9~pre99-1) unstable; urgency=high
+
(`view history`_)
(`view source`_)
More information about the Pkg-jed-commit
mailing list