summaryrefslogtreecommitdiffstats
path: root/debian/README.source
diff options
context:
space:
mode:
Diffstat (limited to 'debian/README.source')
-rw-r--r--debian/README.source95
1 files changed, 95 insertions, 0 deletions
diff --git a/debian/README.source b/debian/README.source
new file mode 100644
index 0000000..e52f2ff
--- /dev/null
+++ b/debian/README.source
@@ -0,0 +1,95 @@
+Building from source
+--------------------
+Install “git-buildpackage” and “devscripts” then run the following:
+
+ debcheckout --git-track '*' util-linux
+ cd util-linux
+ git branch -l | grep debian
+ git checkout master
+ gbp buildpackage
+
+We recommend you use pbuilder to make sure you build in a clean environment:
+
+ gbp buildpackage --git-pbuilder
+
+Patch handling
+--------------
+The official form of modifications to the upstream source are quilt patches in
+debian/patches/, like most Debian packages do. You are welcome to use quilt to
+add or modify patches, but you might prefer using a git commit based approach.
+gbp pq provides that by synthesizing a "patch-queue/<branch>" local branch
+which represents each quilt patch as git commit. You create this with
+
+ gbp pq import --force
+
+Then you are in the patch-queue branch and can git log, commit, cherry-pick
+upstream commits, rebase, etc. there. After you are done, run
+
+ gbp pq export
+
+which will put you back into the debian branch and update debian/patches/
+(including series). You need to git add etc. new patches, add a changelog
+and other packaging changes, and then debcommit as usual.
+
+Rebasing patches to a new upstream version
+------------------------------------------
+gbp pq's "rebase" command does not work very conveniently as it fails on merge
+conflicts. First, ensure you are in the debian branch:
+
+ git checkout master # in case you aren't already on it
+
+Fetch new git history from upstream:
+
+ git remote add kzak git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
+ git fetch kzak [upstream-version-tag]
+
+Now, to import a new upstream release into the existing branch,
+ie. when updating from v2.24 to v2.24.2,
+do:
+
+ gbp pq import --force
+ gbp pq switch # switch back to debian branch from patch-queue branch
+ gbp import-orig --upstream-vcs-tag=v2.24.2 ../tarballs/util-linux-v2.24.2.tar.xz
+ gbp pq switch # switch to patch-queue branch
+ git rebase master
+
+ gbp pq export
+
+Note that our debian/gbp.conf disables patch numbers.
+
+Also, don't forget to commit your newly generated patches!
+
+ git add debian/patches
+ git commit -v
+
+Cherry-picking upstream patches
+-------------------------------
+You can add the util-linux upstream branch as an additional remote to the Debian
+packaging branch. Call it "kzak" or similar to avoid confusing it
+with the already existing "upstream" branch from gbp buildpackage:
+
+ git remote add kzak git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
+ git fetch kzak -n
+
+Now you can look at the upstream log and cherry-pick patches into the
+patch-queue branch:
+
+ gbp pq import --force
+ git log kzak/master
+ git cherry-pick 123DEADBEEF
+
+Finally, export and commit your newly generated debian/patches changes:
+ gbp pq export
+ git add debian/patches
+ git commit -v
+
+Modifying packaging files
+-------------------------------
+
+When making changes to debian/ general "git-buildpackage conventions" apply.
+Follow usual git conventions for commit message but also see "man gbp-dch"
+META TAGS section.
+Finally once you're done update debian/changelog using "gbp dch --auto"
+and commit it.
+
+