RELEASING: Add this file describing the steps to make a release.

These steps might be changing a bit as we work on making the initial
0.1 release.

RELEASING

@@ -0,0 +1,71 @@
+Here are the steps to follow to create a new notmuch release:
+
+1) Verify that what you want to release is committed. The release
+   process will release the code from the current HEAD commit.
+
+2) Verify that the NEWS file is up to date.
+
+	Read through the entry at the top of the NEWS file and see if
+	you are aware of any major features recently added that are
+	not mentioned there. If so, pleas add them, (and ask the
+	authors of the commits to update NEWS in the future).
+
+3) Verify that the notmuch test suite passes.
+
+	Currently this is by running:
+
+		./test/notmuch-test
+
+	And manually verifying that every test says PASS. We plan to
+	fix this to automatically check the results and even to
+	automatically run the test suite as part of a Makefile target
+	described below.
+
+4) Increment the libnotmuch library version in lib/Makefile.local
+
+	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:
+
+		git diff X.Y.Z..HEAD -- lib/notmuch.h
+
+	Note: We currently don't plan to increment
+	LIBNOTMUCH_VERSION_MAJOR beyond 1, so if there *are*
+	incompatible changes to the library interface, then
+	stop. Don't release. Figure out the plan on the notmuch
+	mailing list.
+
+	Commit this change.
+
+5) Increment the notmuch version in Makefile.local
+
+	For most releases we'll just increment the minor number. For
+	major milestones of usability we'll increment the major
+	number.
+
+	Commit this change.
+
+6) Run "make release-publish" which will perform the following steps:
+
+	* 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
+	* Sign the sha1sum using your GPG setup (asks for your GPG password)
+	* 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)
+	* 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
+	  your public-key's setting or this fails.)
+	* Provide some text for the release announcement (see below).
+	  If for some reason you lost this message, "make release-publish-message"
+	  prints it for you.
+
+7) Increment the notmuch version by adding a .1 micro number, commit, and push.
+
+8) Send a message to notmuch@notmuchmail.org to announce the release.
+
+	Use the text from the new entry to NEWS.

lib/Makefile.local

@@ -4,6 +4,13 @@
 # As such, this number must be incremented for any incompatible change to
 # the library interface, (such as the deletion of an API or a major
 # semantic change that breaks formerly functioning code).
+#
+# Note: We don't currently have plans to increment this at this time.
+# If we *do* want to make an incompatible change to the library
+# interface, we'll have to decide whether to increment this (creating
+# a new soname) or to introduce symbol versioning to be able to
+# provide support for both old and new interfaces without having to
+# increment this.
 LIBNOTMUCH_VERSION_MAJOR = 1
 
 # The minor version of the library interface. This should be incremented at