make release: Add a check that version and debian/changelog are consistent

[notmuch] / RELEASING

diff --git a/RELEASING b/RELEASING
index f47ba39c520b7d0272a2044d72c94361019a9566..70a2ec547d2653379c476c99bc9dbd54173a7c07 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,14 +33,46 @@ 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) Upgrade the version in the file "version"
+
+       The scheme for the release number is as follows:
+
+       A major milestone in usability causes an increase in the major
+       number, yielding a two-component version with a minor number
+       of 0, (such as "1.0" or "2.0").
+
+       Otherwise, releases with changes in features cause an increase
+       in the minor number, yielding a two-component version, (such
+       as "1.1" or "1.2").
+
+       Finally, releases that do not change "features" but are merely
+       bug fixes either add increase the micro number or add it
+       (starting at ".1" if not present). So a bug-fix release from
+       "1.0" would be "1.0.1" and a subsequent bug-fix release would
+       be "1.0.2" etc.
+
+       Commit this change.
+
+4) 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 file, and creating a new commit, etc.)
 
-   For the X.Y version, we'll generally just increment Y. But for
-   major milestones of usability we're increment X as well.
+5) Run "make release" which will perform the following steps:
 
-       * Ensure that the caller passed VERSION=X.Y
+       * Ensure that the version consists only of digits and periods
+       * Ensure that version and debian/changelog have the same version
        * 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)
@@ -55,7 +90,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.
+6) 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