[SCM] Qt 4 Debian packaging. branch, master, updated. debian/4.5.2-2-14-g67cabc0
Modestas Vainius
modax-guest at alioth.debian.org
Fri Oct 2 20:28:36 UTC 2009
The following commit has been merged in the master branch:
commit 67cabc061b1da7408c2e40cf3b2f231b0560472d
Author: Modestas Vainius <modestas at vainius.eu>
Date: Fri Oct 2 23:03:53 2009 +0300
Document a couple of workflows.
---
debian/README.source | 216 +++++++++++++++++++++++++++++++++++++++++++++----
debian/changelog | 2 +
debian/upstreamignore | 2 +
3 files changed, 204 insertions(+), 16 deletions(-)
diff --git a/debian/README.source b/debian/README.source
index ff9523b..b8a2d79 100644
--- a/debian/README.source
+++ b/debian/README.source
@@ -5,8 +5,8 @@ Debian patches to the package original source must be stored in debian/patches
directory. Debian patches are applied when the package is built and unapplied
when the package is cleaned. The package uses quilt [1] for managing those
patches. Various tasks of patch management (adding, removing etc.) are
-described in detail in /usr/share/doc/quilt/README.source (provided by quilt
-package of version 0.46-4.1 or later).
+described in /usr/share/doc/quilt/README.source (provided by quilt package of
+version 0.46-4.1 or later).
Public VCS repository of Debian packaging
-----------------------------------------
@@ -23,11 +23,11 @@ Pushing permissions and occasional contributions
* People in debian/control Maintainer and Uploaders (co-maintainers) fields may
freely push changes to public repository.
-* Other members of packaging group should request permission of current
+* Other members of packaging group should request permission of the current
co-maintainers (via IRC or mailing list) before adding yourself to the list of
Uploaders or pushing any other kind of changes.
* Occasional contributors may send patches. Preferably, patches should be
- formatted with `git format-patch` in order to maintain commit origin
+ formatted with `git format-patch` in order to retain commit authorship
information.
* Pushed commits and patches must not violate repository policy as defined
below.
@@ -39,10 +39,10 @@ Committing policy and guidelines
UNRELEASED. That's DEBCHANGE_RELEASE_HEURISTIC=changelog setting for dch.
* New packaging changes must be committed together with the change description
in the debian/changelog entry (if applicable). Sentences should end with dots.
-* The guidelines above are *highly* recommended to follow in order to reduce
+* The guidelines below are *highly* recommended to follow in order to reduce
conflicts in debian/changelog when cherry-picking and merging between
branches:
- * Commits should be atomic (i.e. one change - one commit).
+ * Commits should be self-contained (i.e. one change - one commit).
* It is a good idea to open a new revision with an empty changelog entry (two
empty lines between entry header and trailer) as its own commit. When
packaging a new upstream release, such first commit should include a new
@@ -51,7 +51,7 @@ Committing policy and guidelines
--mainttrailer/-t option in order to reduce maintainer trailer changes.
As a result, dch --release should be used to update the date in the trailer
when releasing the package to Debian.
-* Commit message must be meaningful (typically, debchange is OK). The first
+* Commit message must be meaningful (typically, debcommit is OK). The first
commit message line must be short (up to 72-80 characters) and end with a
dot. More detailed description might be provided in paragraphs wrapped at 80
characters after a empty line (e.g. like a well formatted standard Git commit
@@ -76,15 +76,15 @@ Branches should be named as follows:
unstable. However, if unstable is (semi-)frozen, it may even contain
packaging for experimental. It is up package maintainers what is considered
"current" release.
- * Other mainline packaging branches must be named after Debian release
- codenames (e.g. lenny, squeeze, sid, experimental etc.) that they contain
- packaging of. When such a branch (e.g. experimental) is merged to master,
- it does not need to be deleted from the remote repository.
+ * Other mainline branches must be named after Debian release codenames (e.g.
+ lenny, squeeze, sid, experimental etc.) that they contain packaging of.
+ When such a branch (e.g. experimental) is merged to master, it does not
+ need to be deleted from the remote repository.
* Other packaging "work" branches may be pushed to the remote repository at
- discretion of package mantainer(s). These branches should be deleted from
+ discretion of package maintainer(s). These branches should be deleted from
the public repository when they are no longer needed.
-Non fast forwarding pushes (e.g. rebase of already published history) are
+Non-fast-forwarding pushes (e.g. rebase of already published history) are
forbidden to all mainline packaging branches unless they are absolutely
necessary and have previously been agreed upon by co-maintainers of the
package.
@@ -118,11 +118,195 @@ be used:
$ git tag debian/4.6.0-beta1-1 -sm "4:4.6.0~beta1-1/experimental"
-Suggested packaging workflows
------------------------------
+Versioning of upstream snapshots
+--------------------------------
+
+Since Git commit IDs are not sequential, it is recommended to use a sequential
+number (number of commits since the latest tag) that `git describe` returns at
+the tip of the upstream snapshot being packaged.
+
+For example, if:
+
+ $ git describe
+ v1.2-beta1-45-67890abc
+
+then Debian package upstream version part of this snapshot could be
+1.2~beta1+git45+67890abc.
+
+Cloning public packaging repository
+-----------------------------------
+
+ # For users with ssh access to alioth:
+ $ git clone git.debian.org:/git/path/to/the/remote/repository.git
+
+ # For anonymous users:
+ $ git clone <Vcs-Git URL from debian/control>
+
+ Wait a bit. You will end up with full clone of the public repository and a
+ local branch master will be setup to track remote master branch
+ (origin/master). Change to the directory of the repository.
+
+ In order to track another packaging branch (e.g. lenny) locally, run:
+
+ $ git checkout -b lenny origin/lenny
+
+ Now let's setup `git push` to push all packaging branches and debian tags by
+ default:
+
+ $ git config --add remote.origin.push "refs/heads/master"
+ $ git config --add remote.origin.push "refs/heads/lenny"
+ $ git config --add remote.origin.push "refs/tags/debian/*"
+
+Pulling changes
+---------------
+
+In order to avoid pointless merge commits, it is recommended to use --rebase
+option to `git pull` when pulling changes from the remote repository if your
+local master contains not-yet-pushed and rather trivial commits:
+
+ $ git checkout master
+ $ git pull --rebase
+
+Integrating original source into local repository
+-------------------------------------------------
+
+ Obviously, packaging process requires to have original source next to the
+ debian/ directory. Since it is not allowed to ship upstream source in the
+ public packaging branches, it needs to be retrieved and managed outside
+ packaging branches. Basically, there are a couple of options:
+
+ 1) Original source is extracted to the packaging branch working tree from
+ the tarball:
+
+ # (only once) Ignore everything (upstream source) but files under debian/.
+ $ git config core.excludesfile debian/upstreamignore
+
+ # Checkout a packaging branch
+ $ git checkout master
+
+ # Remove all untracked files including ignored ones. This cleans up the
+ # root directory from old upstream sources (if any)
+ $ git clean -xdff
+
+ # Extract upstream source code into packaging branch working tree
+ $ tar zxvf ../qt4-x11_4.5.2.orig.tar.gz --strip=1
+
+ # Do packaging, committing, finally push...
+
+ 2) Original source is maintained in the separate (local) branch(es) and is
+ read into the packaging branch as needed:
+
+ a) If original source comes in the form of the tarball, it can be
+ maintained in the local 'upstream' branch. When creating such a new
+ disjoint upstream branch, execute:
+
+ # Switch HEAD to not-yet-created upstream branch
+ $ git symbolic-ref HEAD refs/heads/upstream
+
+ When updating an existing upstream branch to a new release, just do:
+
+ # Clean current branch before checkout
+ $ git clean -xdff
+ $ git checkout upstream
+
+ Then do something like this:
+
+ # Remove all tracked files (e.g. old sources)
+ $ git rm -r '*'
+
+ # Extract tarball into the repository
+ $ tar zxvf ../qt4-x11_4.5.2.orig.tar.gz --strip=1
+
+ # Add all files to the index and commit the result
+ $ git add -A
+ $ git commit -m "Import upstream 4.5.2 release."
+
+ b) Original source can be fetched from the remote upstream repository.
+ For example, let's define a new remote 'qt' for original Qt sources.
+
+ $ git remote add qt git://gitorious.org/qt/qt.git
+ $ git remote update
+ # Wait ...
+ $ git branch upstream qt/master # optional
+
+ Finally, read upstream tree to the packaging branch working tree, do:
+
+ # (only once) Ignore everything (upstream source) but files under
+ # debian/.
+ $ git config core.excludesfile debian/upstreamignore
+
+ # Make sure there are no dangling untracked files
+ $ git clean -xdff
+
+ # Checkout packaging branch
+ $ git checkout master
+
+ # Read upstream (can be any git commit'ish/tree'ish reference) sources
+ # into the working tree
+ $ git read-tree upstream
+ $ git checkout-index -a
+ $ git reset
+
+ # Do packaging, committing, finally push...
+
+ 3) Do all packaging work in the private 'build' branch which is a merge of
+ upstream (2a or 2b) and packaging branch. This scenario might be quite
+ error prone and time consuming since packaging commits must be done in the
+ packaging branch rather than build branch or later cherry-picked from the
+ build to master branch.
+
+ a) Committing to master directly:
+
+ $ git checkout build # (or git checkout -b build upstream)
+ $ git merge upstream # (or git reset --hard upstream)
+ $ git merge master
+
+ # Do work
+ $ git checkout master
+ $ git commit
+ $ git checkout build
+ $ git merge master
+
+ # Do more work
+ $ git checkout master
+ $ git commit
+ ...
+
+ b) Cherry-picking (or rebasing) from build branch:
+
+ $ git checkout build # (or git checkout -b build upstream)
+ $ git merge upstream # (or git reset --hard upstream)
+ $ git merge master
+
+ # Do work
+ $ git commit
+ # Do more work
+ $ git commit
+ ...
+ # Done. Now merge packaging changes back to master.
+
+ # Either
+ $ git checkout master
+ $ git cherry-pick commit1
+ $ git cherry-pick commit2
+ ...
+ $ git branch -D build # build branch becomes useless
+
+ # OR convert build branch into master using rebase
+ $ git rebase -i --onto master `git merge-base upstream master`
+ $ git checkout master
+ $ git reset --hard build
-TODO
+ # Tag, push etc.
+ Feel free to use whatever workflow you like most (or any other). In general,
+ workflow #3 looks more cumbersome but it's nearer the proper Git way.
+ However, workflows #1 are #2 are somewhat simpler even if lower level git
+ commands are used. What is more, they give you less headache when managing
+ patches with quilt because Git is told to ignore everything but debian/
+ subdirectory hence it won't track changes made by `quilt push`. This way you
+ can always be sure that `git commit -a` won't pick up any raw patches to
+ upstream source regardless if anything is quilt pushed or not.
[1] Available in the quilt package on Debian based systems. quilt must be
invoked with QUILT_PATCHES environment variables set to debian/patches.
diff --git a/debian/changelog b/debian/changelog
index ed5e1b2..b00381a 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -14,6 +14,8 @@ qt4-x11 (4:4.5.3-1) UNRELEASED; urgency=low
* VCS changed to git, adjust Vcs-* field in debian/control accordingly.
* Bump Standards-Version to 3.8.3: no changes needed.
+ * Document Git repository policy and packaging workflows in
+ debian/README.source.
+++ Changes by Fathi Boudra:
diff --git a/debian/upstreamignore b/debian/upstreamignore
new file mode 100644
index 0000000..834a50e
--- /dev/null
+++ b/debian/upstreamignore
@@ -0,0 +1,2 @@
+/*
+!/debian/
--
Qt 4 Debian packaging.
More information about the pkg-kde-commits
mailing list