Thomas Koch: Design document for a patch management system on a DVCS
Dear friends of Debian,this is my first post to Planet Debian. - The planet with the most geeky registration procedure in the known universe!
I proposed an alternative to topgit some days ago on the vcs-pkg.org list. Martin asked (and encouraged) me to give a better explanation of the idea, which I'll hereby try. Sorry for not giving any drawings, but I'm totally incapable of anything graphical.
Hopefully, I'll manage to come to the Debian Miniconf in Berlin. Then we could discuss the idea further and maybe even start implementing it. (Somebody would need to help me with my first steps in Perl then...)
The following text is available on github. Please help me expand it!
Design document for a patch management system on a DVCS
Requirements
The system to implement manages patchsets. A patchset is a set of patches with
a tree-ish dependency graph between the patches. There's one distinct root of
this dependency graph.
Patches are managed as branches with each branch representing a patch.
Modification of a patch is done by a commit to the respective branch. A branch
representing a patch as part of a patchset is called patchbranch.
The patch of a patchbranch is created as the diff between the root of the
patchbranch and the head.
The most important management methods are:
- Export a patchset in different formats
- quilt
- a merged commit of all patches
- a line of commits with each commit representing one patch
- Update a patchset against an updated root.
- Copy a patchset
- Delete a patchset from direct visibility while preserving all history about
it
- Hide and unhide a patchset from direct visibility
Additional requirements:
- The system should be implementable on top of GIT, Mercurial and eventually
Bazaar.
- The system must easily cope with multiple different and independent patchsets.
- All information about a patchset must be encoded in one distinct branch.
Publishing this one branch must be sufficient to allow somebody else to
recreate the patchset with all of its patchbranches.
- The system should not rely on the presence of hooks.
- The system should not require the addition of management files in patch
branches (like .topmsg and .topdeps in topgit)
- The system must be easy to understand for a regular user of the underlying
DVCS.
- The implementation may allow a patchset to depend on another patchset(s).
implementation
patchset meta branch
A patchset meta branch holds all informations about one patchset. First, it
holds references to the top commits of all patch branches in the form of parent
references of commits. Thus pushing the patchset meta branch automatically also
pushes all commits of all patch branches.
Secondly, the patchset meta branch contains meta informations about the
patchset. These meta informations are:
- The names of all patch branches together with the most recent commit
identifier of a particular patch branch. Let's save this information in a
file called branches.
- A message for each patch branch that explains the patch. These messages can
be saved in the file tree as msg/$ PATCH-BRANCH-NAME
- References to the dependencies of the patch (other patches of the same
patchset or the root of the patchset). This is also encoded in the file
branches.
Since the patchset meta branch holds all this informations, it is possible, to
delete all patch branches and recreate them from this informations.
Although the commits of the patchset meta branches hold references to the patch
branches, its file tree does not need to contain any files from the referenced
patches. This may confuse the underlying DVCS, but the patch meta branch is not
ment to be directly inspected.
The branches file
A branches file for a fictive patchset could look like:
# patch branches without an explicit dependency depend on the root of the
# patchset tree
# A Root can be given as either a fix commit (seen here), a branch or a tag.
# A fixed commit or tag is useful to maintain a patchset against an older
# upstream version
ROOT: 6a8589de32d490806ab86432a3181370e65953ca
# A tag as a dependency
#ROOT: upstream/0.1.2
# A branch as a dependency
#ROOT: upstream
# A regular patch with it's name and last commit
BRANCH: debian/use-debian-jars-in-build-xml 4bab542c261ff1a1ae87151c3536f19ef02d7937
# two other regular patches
BRANCH: upstream-jira/HDFS-1234 a8e4af13106582ca1bfbbcaeb0537f73faf46d87
BRANCH: upstream-jira/MAP-REDUCE-007 e3426bcbcb2537478f851edcf6eb04b34f6c7106
# This patch depends on the above two patches
# The sha1 below the dependency patches references a merge commit of the two
# dependencies
BRANCH: upstream-jira/HDFS-008 517851aa829d77e09bc5e59985fed1b0aa339cc6
DEPENDENCIES:
upstream-jira/HDFS-1234
upstream-jira/MAP-REDUCE-007
cc294f2e4773c4ff71efb83648a0e16835fca841
# A patch branch that belongs to the patch branch, but won't get exported (yet)
BRANCH: upstream-jira/HDFS-9999 74257905azgsa4689bc5e59985fed1b0aa339cc6
BRANCH-FLAGS: noexport
- Export a patchset in different formats
- quilt
- a merged commit of all patches
- a line of commits with each commit representing one patch
- Update a patchset against an updated root.
- Copy a patchset
- Delete a patchset from direct visibility while preserving all history about it
- Hide and unhide a patchset from direct visibility
- The system should be implementable on top of GIT, Mercurial and eventually Bazaar.
- The system must easily cope with multiple different and independent patchsets.
- All information about a patchset must be encoded in one distinct branch. Publishing this one branch must be sufficient to allow somebody else to recreate the patchset with all of its patchbranches.
- The system should not rely on the presence of hooks.
- The system should not require the addition of management files in patch branches (like .topmsg and .topdeps in topgit)
- The system must be easy to understand for a regular user of the underlying DVCS.
- The implementation may allow a patchset to depend on another patchset(s).
- The names of all patch branches together with the most recent commit identifier of a particular patch branch. Let's save this information in a file called branches.
- A message for each patch branch that explains the patch. These messages can be saved in the file tree as msg/$ PATCH-BRANCH-NAME
- References to the dependencies of the patch (other patches of the same patchset or the root of the patchset). This is also encoded in the file branches.
# patch branches without an explicit dependency depend on the root of the
# patchset tree
# A Root can be given as either a fix commit (seen here), a branch or a tag.
# A fixed commit or tag is useful to maintain a patchset against an older
# upstream version
ROOT: 6a8589de32d490806ab86432a3181370e65953ca
# A tag as a dependency
#ROOT: upstream/0.1.2
# A branch as a dependency
#ROOT: upstream
# A regular patch with it's name and last commit
BRANCH: debian/use-debian-jars-in-build-xml 4bab542c261ff1a1ae87151c3536f19ef02d7937
# two other regular patches
BRANCH: upstream-jira/HDFS-1234 a8e4af13106582ca1bfbbcaeb0537f73faf46d87
BRANCH: upstream-jira/MAP-REDUCE-007 e3426bcbcb2537478f851edcf6eb04b34f6c7106
# This patch depends on the above two patches
# The sha1 below the dependency patches references a merge commit of the two
# dependencies
BRANCH: upstream-jira/HDFS-008 517851aa829d77e09bc5e59985fed1b0aa339cc6
DEPENDENCIES:
upstream-jira/HDFS-1234
upstream-jira/MAP-REDUCE-007
cc294f2e4773c4ff71efb83648a0e16835fca841
# A patch branch that belongs to the patch branch, but won't get exported (yet)
BRANCH: upstream-jira/HDFS-9999 74257905azgsa4689bc5e59985fed1b0aa339cc6
BRANCH-FLAGS: noexport
As I really liked
I'm thinking about distributed issue tracking systems that play nice
with git. I don't care about other version control systems anymore :).
I also prefer command line interfaces, because as commentators on the
blog have mentioned, I'm a Luddite (in the imprecise, slang sense).
So far I have found a few projects, and tried to guess how much of a
going concern they are.
Git Specific
On FOSDEM 2010 we agreed on several bigger changes in phpMyAdmin. The two of
them were my proposals and I had to take care of them - migration to Git and
start to use Gettext based system for translating phpMyAdmin.
The migration to Git was quite straightforward and went alive on 11th of
March. There were few tiny issues afterwards, but I think everything went
quite smoothly and we can happily use it right now (I especially enjoy using
feature branches). I've also written little
Fourteen months after the renaming of the Free/Open Source code of
GForge 4.x to the new FusionForge name, we're pleased to announce
version 5.0. As mentioned in the release notes, this is still an
incremental step over version 4.8 rather than a revolution, but the
changes are important enough, and numerous enough, that we felt it
justified to bump the major version number.
Major improvements, beyond a host of bugfixes, include:








Maintaining stable life with unstable distro?
This post may sound ludicrous to some of you but please hear me out. I ve been on Debian unstable/Sid for awhile now and it was all cool until yesterday.
Besides my work on Debian DebConf/some devel, I m university student, also I do web devel which is my primary source of income, besides all those I try to go out on weekends and have some kind of social life. Somehow I manage to do all these things and I d say I manage them pretty successfully too.
Now I m hardcore to the bone, but this is just too much, last week started working on immense web devel project didn t sleep more then 2hrs/day whole week; I also didn t shut down my notebook and just kept it on suspend as I usually do. Either way I was about to print/scan something and I connect my printer and what happens? My whole system freezes, now I ll let you figure out the result of doing hard reset and having a lot of gedit docs open at that time. And yes, I did had that bug reported awhile ago, can t find it now, but it was fixed, seems like it s back again.
In the end I m left with weekend completing the lost work + late school work + eclipse 3.5.2-2 ought to be uploaded. I do almost all the work (didn t upload eclipse) and literally pass out on Sunday. Wake up sometime on Monday, wasn t able to get up from bed.
Today is March 24th, that means
I'm now on my way back from The first miniDebCamp and miniDebconf that
happened from March 13th to March 19th in Khon Kaen, Thailand.
This even was organized locally by a team of very motivated Thai
Debian enthusiasts and contributors, such as Theppitak Karoonboonyanan
(*the* Thai DD), Neutron Soutmun, Kitt Tientanopajai, and all those whose name I'm
not remembering as of now (I hope they won't mind).
The even had kinda the structure of DebConfs, with a few days of "Debcamp"
to begin. See the
Dear New Yorkers,
I'm going to speak at Free Culture NYU about my current project,