RELEASING: Add a (manual!) step to create a debian/changelog entry

[notmuch] / RELEASING

diff --git a/RELEASING b/RELEASING
index 8e628d7f44f8a361de1f4f591e1a51ee9665fc44..99c6d79ecb86812471fab6adefe795ce42ace68a 100644 (file)
--- a/RELEASING
+++ b/RELEASING
@@ -16,13 +16,16 @@ repository. From here, there are just a few steps to release:
        not mentioned there. If so, pleas add them, (and ask the
        authors of the commits to update NEWS in the future).
 
-2) Increment the libnotmuch library version in lib/Makefile.local
+2) Verify that the library version in lib/Makefile.local is correct
 
-       See the instructions there for how to increment it. The
-       command below can be useful for inspecting header-file changes
-       since the last release X.Y.Z:
+       See the instructions there for how to increment it.
 
-               git diff X.Y.Z..HEAD -- lib/notmuch.h
+       The version should have been updated with any commits that
+       added API, but do check that that is the case. The command
+       below can be useful for inspecting header-file changes since
+       the last release X.Y:
+
+               git diff X.Y..HEAD -- lib/notmuch.h
 
        Note: We currently don't plan to increment
        LIBNOTMUCH_VERSION_MAJOR beyond 1, so if there *are*
@@ -30,24 +33,38 @@ repository. From here, there are just a few steps to release:
        stop. Don't release. Figure out the plan on the notmuch
        mailing list.
 
+       Commit this change, if any.
+
+3) Create an entry for the new release in debian/changelog
+
+       The syntax of this file is tightly restricted, but the
+       available emacs mode (see the dpkg-dev-el package helps).  The
+       entries here will be the Debian-relevant single-line
+       description of changes from the NEWS entry. And the version
+       must match the version in the next step.
+
        Commit this change.
 
-3) Run "make VERSION=X.Y release" which will perform the following steps:
+       XXX: It would be great if this step were automated as part of
+       release, (taking entries from NEWS and the version from the
+       VERSION, and creating a new commit).
+
+4) Run "make VERSION=X.Y release" which will perform the following steps:
 
    For the X.Y version, we'll generally just increment Y. But for
    major milestones of usability we're increment X as well.
 
+       * Ensure that the caller passed VERSION=X.Y
+       * Verify that the source tree is clean
        * Compile the current notmuch code (aborting release if it fails)
        * Run the notmuch test suite (aborting release if it fails)
-       * Check that the notmuch version consists of only two components
-       * Check that no release exists with the current version
-       * Verify that "make dist" completes successfully
        * Generate the final tar file
-       * Generate an sha1sum file
+       * Generate a .sha1 sum file for the tar file
        * Sign the sha1sum using your GPG setup (asks for your GPG password)
+       * Check that no release exists with the current version
        * scp the three files to appear on http://notmuchmail.org/releases
-       * Place local copies of the three files in the releases directory
        * Create a LATEST-notmuch-version file (after deleting any old one)
+       * Place local copies of the three files in the releases directory
        * Tag the entire source tree with a tag of the form X.Y.Z, and sign
          the tag with your GPG key (asks for your GPG password, and you
          may need to set GIT_COMMITTER_NAME and GIT_COMMITTER_EMAIL to match
@@ -55,7 +72,7 @@ repository. From here, there are just a few steps to release:
        * Push that tag
        * Provide some text for the release announcement (see below).
 
-4) Send a message to notmuch@notmuchmail.org to announce the release.
+5) Send a message to notmuch@notmuchmail.org to announce the release.
 
        Use the text provided from "make release" above, (if for some
        reason you lose this message, "make release-message" prints