Re: Call for teams interested in collaborating on a 'standard' Git workflow
Hi,
debconf is fantastic in that it gave me the possibility to discuss with many
people and rework my ideas about patch management. The ideas now feel right.
I've attached a draft of a description of the workflow.
Before continuing with the description I'll now try to find my way around the
git-buildpackage source code as long as Guido is still around. I'd love to
hear feedback whether the description is understandable and the ideas are
sane.
Best regards,
Thomas Koch, http://www.koch.ro
The proposed patch management workflow in this document has many similarities with git-pq. It differs in these points:
* Patch branches all originate in upstream or in the branches they depend on. git-pq puts all patches on one line.
* The commit objects of patch branches are conserved in a normal packaging workflow even though users only share the usual upstream, master, build branches and release tags.
* This workflow allows to make use of GIT's merge capabilities.
For the purpose of this document, the master branch is the branch where /debian/ lives. Others like to call this branch e.g. "debian".
==Most basic workflow, without patches, sane upstream==
upstream
|
| master
| |
| /* merge, new debian version (n commits)
|/ |
* | new upstream version
| |
| * debianize, debian release (n commits)
| /
|/
* import upstream
==Upstream needs clean up to be dfsg compliant==
upstream
|
| dfsg_clean
| |
| | master
| | |
| | * new debian version
| | /|
| |/ |
| * | merge, clean up (n commits)
| /| |
|/ | |
* | | import new unmodified upstream
| | |
| | * debianize, debian release
| | /
| |/
| * merge, clean up (n commits)
| /
|/
* import unmodified upstream
==Patches, dfsg free upstream==
===principles, requirements, concepts===
* Patches should not be merged to the master branch, because it's hard to "unmerge".
* We want to use GIT's merge capabilities and other features, therefor we'd like to work on patches in seperate branches per patch.
* It should be much easier to use then topgit
* We don't want to be forced to pull/push douzens of patch branches.
* We don't want to (permanently) pollute the branch namespace
===Design===
* When a new release has been merged to master, a new build branch is forked from master: build-$UPSTREAM_VERSION
* Patch branches are only merged in such build branches, never in the master branch
* Later we can delete the build branches but we still keep the commits since we tag each Debian release
* The primary storage of patches are patch files in quilt format in debian/patches in the master branch
* We provide tooling to convert patch branches into annotated quilt patches and recreate *identical* patch branches from quilt files.
* We add extra headers in [http://dep.debian.net/deps/dep3/ dep-3] format to the quilt files in debian/patches:
** git-commit: SHA-1 value of the HEAD of the patch branch
** git-base-commit: SHA-1 value of the base commit of the patch branch (only necessary if git-base-name is not the UPSTREAM_BRANCH)
** git-dependencies: list of branch names of dependencies of this patch branch
===Workflow===
Creating patches:
# Checkout patch branch from upstream (or from the branch it depends on).
# Hack, commit
# Create an annotated quilt patch from the patch branch
# repeat the above for other patch branches
# merge the patch branches into the build branch
# Once the patches are merged in the build branch, the patch branches can be deleted.
Editing patches:
# Recreate the patch branches with informations from the quilt annotations
# Hack, commit
# update quilt files
# merge updated patch branches into build branch
Update upstream:
# Import upstream, merge into master
# recreate the patch branches
# either merge upstream changes into each patch branch or rebase patch branches
# hack on patch branches
# update quilt files
# checkout a new build branch from master
# merge updated patch branches into build branch
===Tooling===
The outlined workflow could be done manually without new tools. It's however only practical, if additional tools are provided.
This section describes the necessary tools to be implemented.
environment variables:
* UPSTREAM_BRANCH - the name of the upstream branch, default "upstream", may need to be changed to dfsg_clean
====create quilt file====
options:
* dependency branches [optionally, defaults to empty=UPSTREAM_BRANCH]
* base [optionally, defaults to SHA-1 of UPSTREAM_BRANCH]
* head [optionally, defaults to SHA-1 of current HEAD]
* name [optionally, defaults to current HEAD name]
* target [optionally, defaults to debian/patches/$BRANCH_NAME]
Creates a quilt patch file from a patch branch or updates an existing one, inheriting options from an exisiting quilt file.
====checkout branch from quilt file====
options:
* branch name (translates to the quilt file's name)
* checkout [boolean, defaults to true]
Creates a branch with the given name pointing to the commit specified in the git-commit line of the quilt file. Checks out the branch if checkout option is true.
====merge patch branch(es)====
options:
* target branch
* name [optionally, n-times, names of branches to merge]
Merges all patch branches into the target branches. Creates the target branch if it doesn't exist yet.
====status====
options:
* build branch [optionally]
Gives the following informations:
* list of patches (according to files in debian/patches)
* which patches needs update (because dependency or upstream was updated)
* which patches don't have their commit objects in the object database
* which patches have not yet been merged in the build branch
==links==
* man git-quiltimport
* quilt headers http://dep.debian.net/deps/dep3/
Reply to: