Much more detail about how to build the source package from VCS.

diff --git a/debian/README.source b/debian/README.source
index 2484998..ea0f5a8 100644 (file)
--- a/debian/README.source
+++ b/debian/README.source
@@ -1,8 +1,9 @@
+======================================================
 Building the Debian source package for python-coverage
 ======================================================
 
 Pristine upstream source contains non-DFSG-free files
------------------------------------------------------
+=====================================================
 
 The pristine upstream source contains obfuscated files, that are thereby
 not appropriate for use as source files. This violates DFSG §2.
@@ -14,8 +15,15 @@ The ‘debian/watch’ configuration specifies that ‘uscan --download’ will
 re-pack the pristine upstream tarball by running ‘debian/repack’.
 
 
-Build source package from VCS
------------------------------
+Package maintenance in VCS
+==========================
+
+The ‘debian/control’ file declares the VCS repository used for
+tracking the Debian package maintenance work.
+
+
+VCS branches for package maintenance
+------------------------------------
 
 The source for the Debian packaging is managed in these conventional
 Git branches:
@@ -25,20 +33,98 @@ Git branches:
 * upstream: Upstream source code base, as imported from tarballs.
 * pristine-tar: Metadata for reproducibly generating upstream tarball.
 
-To build the source package from the Git VCS, use the Debian ‘gitpkg’
-tool to generate all the files::
 
-    $ git checkout master
-    $ gitpkg packaging upstream
+Work on a release in VCS
+------------------------
+
+* Ensure the ‘upstream’ branch contains the correct upstream source.
+
+* Ensure the ‘pristine-tar’ branch contains the corresponding metadata
+  for the pristine upstream source tarball.
+
+* In the ‘packaging’ branch, create a new Debian changelog entry.
+
+  Because the release is not complete, many aspects have not been
+  decided and should not be recorded in the VCS:
+
+  * The target destination (in the header) is “UNRELEASED”.
+
+  * The person and timestamp of the release is undecided, so should be
+    empty: the signature line should have no content, just the “ --”
+    leader.
+
+* While working on the package, temporarily finalise the signature
+  line for testing the build.
+
+  This ephemeral state should not be part of the VCS history, though,
+  so do not commit that finalised changelog entry; revert it to the
+  above state to continue development.
+
+
+Build the source package from VCS
+---------------------------------
+
+* Ensure the ‘packaging’ branch contains all the changes that are
+  intended for the release to Debian.
+
+* Until the work is ready for release, do not commit a finalised
+  Debian changelog entry. The changelog entry should be in the state
+  described in “Work on a release in VCS”, above.
+
+  This correctly leaves the decision of which destination for the
+  upload, who uploads and when, to the point in time where that
+  decision is made: the time of finalising the release.
+
+* Rebase a working branch, e.g. ‘wip/packaging/4.2+dfsg.1-1’, from the
+  HEAD of ‘packaging’.
+
+* In this branch, finalise the ‘debian/changelog’:
+
+  * Declare a release name, e.g. “* The “Ananta Bijoy Das” release.”
+
+  * Set the target distribution, e.g. “unstable”.
+
+  * Set the signature line containing the correct person and timestamp,
+    e.g. “Ben Finney <[email protected]>  Tue, 09 Aug 2016 06:05:28 +1000”.
+
+  * Commit the finalised changelog with a commit message of the form
+    “Finalise release “4.2+dfsg.1-1”.”
+
+* Test the source package in ‘master’:
+
+  * Merge the ‘upstream’ branch to ‘master’, with the commit message
+    “Merge upstream version “4.2+dfsg.1”.”.
+
+  * Merge – but *do not yet* commit – the work-in-progress release
+    branch ‘wip/packaging/4.2+dfsg.1-1’, into ‘master’.
+
+  * Build the source package from the resulting working tree.
+
+  * Test the source package by building it in a Sbuild or Pbuilder
+    environment, with all Lintian checks enabled.
+
+* Upload the successfully-built source package to Debian.
+
+* Only when the package builds satisfactorily from the merged working
+  tree in ‘master’:
+
+  * Commit the merged release to ‘master’, with the commit message of
+    the form “Merge Debian packaging for release “4.1+dfsg.1-2”.”.
+
+  * Create and sign a tag for the release, ‘debian/4.2+dfsg.1-1’ with
+    the commit message “Debian release “4.2+dfsg.1-1.”.
+
+* Prepare the ‘packaging’ branch for ongoing work:
+
+  * Switch to the ‘packaging’ branch.
+
+  * Fast-forward merge the finalised changelog from
+    ‘wip/packaging/4.2+dfsg.1-1’.
 
-The ‘dpkg-source’ process will complain about the “deletion” of
-upstream source. This is because the upstream source is not present at
-all in the ‘packaging’ branch exported, but in the ‘upstream’ branch.
-The upstream source is safely exported earlier in its own tarball.
+  * Delete the work-in-progress branch ‘wip/packaging/4.2+dfsg.1-1’.
 
-The generated source package is the source control file
-‘../deb-packages/python-coverage/python-coverage_$DEBIANVER.dsc’ and
-its associated files in that directory.
+  * Optionally: Create a new work-in-progress for an upcoming release,
+    as described in “Work on a release in VCS”, above.
 
 
- -- Ben Finney <b[email protected]>, Sun, 24 Apr 2016 11:55:09 +1000
+ -- Ben Finney <b[email protected]>, Fri, 12 Aug 2016 10:31:15 +1000

diff --git a/debian/changelog b/debian/changelog
index d43c5df..3ca9b2b 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -2,6 +2,8 @@ python-coverage (4.2+dfsg.1-2) UNRELEASED; urgency=medium
 
   * debian/*:
     * Update my email address for Debian work.
+  * debian/README.source:
+    * Much more detail about how to build the source package from VCS.
 
  --