RELEASING: Make X.Y.Z versions less ambiguous

The document uses X.Y.Z to sometimes mean the previous release version,
and in other places to mean the upcoming next release version.  Identify
these more explicitly.

1 files changed, 50 insertions, 21 deletions

diff --git a/RELEASING b/RELEASING
index ee4a6e341..da5b7b0df 100644
--- a/RELEASING
+++ b/RELEASING
@@ -43,14 +43,44 @@ Here are the steps to follow to create a new cairo release:
 
 		DISPLAY= CAIRO_TEST_TARGET=" "
 
-3) Fill out an entry in the NEWS file
+3) Decide what the new version number for the release will be.
+
+	There are three types of releases:  Minor, Micro, and
+	Snapshot.  Micro releases should be only bugfixes and no API
+	additions.  If there are API additions consider making a Minor
+	release.  Snapshot releases can be done of the current
+	development tree between Minor releases, as desired.
+
+	Cairo uses even numbers for official releases, and odd numbers
+	for development snapshots.  Thus, for a Minor release the
+	version numbers should be:
+
+		LAST_RELEASE="X.Y.Z"     # e.g. 1.14.4
+		THIS_RELEASE="X.Y+2.0"	 # e.g. 1.16.0
+
+	While for a micro release it would be:
+
+		LAST_RELEASE="X.Y.Z"     # e.g. 1.16.0
+		THIS_RELEASE="X.Y.Z+2"   # e.g. 1.16.2
+
+	Snapshots are similar but have odd minor versions, e.g.:
+
+		LAST_RELEASE="X.Y.Z"     # e.g. 1.16.2
+		THIS_RELEASE="X.Y+1.0"   # e.g. 1.17.0
+
+	and subsequent snapshots in that series are just normal micro
+	releases:
+
+		LAST_RELEASE="X.Y.Z"     # e.g. 1.17.0
+		THIS_RELEASE="X.Y.Z+2"   # e.g. 1.17.2
+
+
+4) Fill out an entry in the NEWS file
 
 	Sift through the logs since the last release. This is most
 	easily done with a command such as:
 
-		git log --stat X.Y.Z..
-
-	where X.Y.Z is the previous release version.
+		git log --stat ${LAST_RELEASE}..
 
 	Summarize major changes briefly in a style similar to other
 	entries in NEWS. Take special care to note any additions in
@@ -61,12 +91,12 @@ Here are the steps to follow to create a new cairo release:
 
 		find src/ -name '*.h' ! -name '*-private.h' \
 		  ! -name 'cairoint.h' ! -name 'cairo-*features*.h' | \
-		xargs git diff X.Y.Z.. --
+		xargs git diff ${LAST_RELEASE}.. --
 
 	Include a link to the incremental ChangeLog for this release,
 	which we'll be uploading in a later step:
 
-		http://cairographics.org/releases/ChangeLog.X.Y.Z
+		http://cairographics.org/releases/ChangeLog.${THIS_RELEASE}
 
 4) Increment cairo_version_{minor|micro} in cairo-version.h:
 
@@ -102,11 +132,11 @@ Here are the steps to follow to create a new cairo release:
 	* Sign the sha1sum using your GPG setup (asks for your GPG password)
 	* scp the three files to appear on http://cairographics.org/releases
 	* Generate a versioned manual and upload it to appear as both:
-	  http://cairographics.org/manual-X.Y.Z
+	  http://cairographics.org/manual-${THIS_RELEASE}
 	  http://cairographics.org/manual
 	* Place local copies of the three files in the releases directory
 	* Create a LATEST-package-version file (after deleting any old one)
-	* Tag the entire source tree with a tag of the form X.Y.Z, and sign
+	* Tag the entire source tree with a ${THIS_RELEASE} tag, 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.)
@@ -117,26 +147,27 @@ Here are the steps to follow to create a new cairo release:
 	Upload the incremental ChangeLog generated by the above:
 
 		scp ChangeLog.cache-X.Y.Z-1.. \
-		    cairographics.org:/srv/cairo.freedesktop.org/www/releases/ChangeLog.cairo-X.Y.Z
+		    cairographics.org:/srv/cairo.freedesktop.org/www/releases/ChangeLog.cairo-${THIS_RELEASE}
 
 	To undo a release-publish, before you've sent any emails or
 	pushed changes to master, delete the locally created tag (git
-	tag -d X.Y.Z); then log into the webserver, repoint the manual
-	and LATEST-cairo-X.Y.Z symlinks to the previous versions, remove
-	manual-X.Y.Z and release/cairo-1.14.4.
+	tag -d ${THIS_RELEASE}); then log into the webserver, repoint
+	the manual and LATEST-cairo-${THIS_RELEASE} symlinks to the
+	previous versions, remove manual-${THIS_RELEASE} and
+	release/cairo-${THIS_RELEASE}.
 
 7) Update trunk (or the stable branch) version number.
 
-	For micro releases (X.Y.Z), increment cairo_version_micro to the next
-	larger (odd) number in cairo-version.h, commit, and push.
+	For Micro releases (X.Y.Z), increment cairo_version_micro to the
+	next larger (odd) number in cairo-version.h, commit, and push.
 
-	For minor releases (X.Y.0), increment cairo_version_minor to the next
-	larger (odd) number, and set cairo_version_micro to 1.  Then commit
-	and push.
+	For Minor releases (X.Y.0), increment cairo_version_minor to the
+	next larger (odd) number, and set cairo_version_micro to 1.  Then
+	commit and push.
 
 8) Push the new tag out to the central tree with a command like:
 
-	git push origin master X.Y.Z
+	git push origin master ${THIS_RELEASE}
 
 9) Edit the cairo bugzilla product and add the new version numbers.
 
@@ -155,9 +186,7 @@ Here are the steps to follow to create a new cairo release:
 	get more information about cairo" blurbs from README, and finally
 	the shortlog of all changes since last release, generated by:
 
-		git shortlog X.Y.Z...
-
-		where X.Y.Z is the last released version.
+		git shortlog ${LAST_RELEASE}...
 
 11) Add the announcement to the NEWS page and the front page.