path: root/RELEASING

Here are the steps to follow to create a new cairo release:

0) Decide type of release and checkout the appropriate branch.

	The Cairo project makes three types of releases: Development
	snapshot releases, stable minor releases, and stable micro (aka
	"point") releases.  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.

	For stable releases (both minor and micro), the work should be
	done on the given release branch.  E.g. for 1.14.12, check out
	the 1.14 branch via "git checkout origin/1.14 -b 1.14".

1) Ensure that there are no local, uncommitted/unpushed mods.

	You're probably in a good state if both "git diff
	HEAD" and "git log master..origin/master" give no output.  Also make
	sure you have libglib2.0-doc installed (else you'll get
	excessive gtk-doc cross reference warnings in the next step).

2) Verify that the code passes "make distcheck"

	First, make sure you have 'nm' and 'readelf' commands in PATH.
	this should be OK with any Linux distro.

	Running "make distcheck" should result in no warnings or
	errors and end with a message of the form:

	=============================================
	cairo-X.Y.Z archives ready for distribution:
	cairo-X.Y.Z.tar.gz
	=============================================

	(But the tar file isn't actually ready yet, as we still have
	some more steps to follow).

	Note that it's allowed (and perhaps recommended) to run the
	"make distcheck" step against an all-software X server such as
	Xvfb to avoid getting tripped up by any	X-server-driver-specific
	bugs. See test/README for details

	If you get errors about local PLT entries, you get the list of
	cairo entries with the error.  For each of these, a call to
	slim_hidden_def and slim_hidden_proto is needed in the cairo
	implementation in the style of other similar calls.

	In the unfortunate case that you have to push a snapshot out
	(note, I said snapshot, not release) without the entire test
	suite passing, here's the magic env vars to set when doing
	'make distcheck' and 'make release-publish' that will let you
	get away with it.  At any cost, never ever release without
	(implied) distchecking.	 Every time we got around it, it turned
	out to be a disaster.  Anyway, here's the pass code:

		DISPLAY= CAIRO_TEST_TARGET=" "

3) Decide what the new version number for the release will be.

	Cairo uses even numbers for official releases, and odd numbers
	for development snapshots.  Thus, for a Minor release it would
	be:

		LAST_RELEASE="X.Y.Z"     # e.g. 1.12.0
		THIS_RELEASE="X.Y+2.0"	 # e.g. 1.14.0

	While for a Micro release the version numbers should be:

		LAST_RELEASE="X.Y.Z"     # e.g. 1.14.0
		THIS_RELEASE="X.Y.Z+2"   # e.g. 1.14.2

	Snapshots are similar but have odd minor versions.  Also, the
	first snapshot release in a new series will be .2 rather than
	.0, e.g.:

		LAST_RELEASE="X.Y.Z"     # e.g. 1.14.0
		THIS_RELEASE="X.Y+1.0"   # e.g. 1.15.2

	and subsequent snapshots in that series are just normal micro
	releases:

		LAST_RELEASE="X.Y.Z"     # e.g. 1.15.2
		THIS_RELEASE="X.Y.Z+2"   # e.g. 1.15.4

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 ${LAST_RELEASE}..

	Summarize major changes briefly in a style similar to other
	entries in NEWS. Take special care to note any additions in
	the API. These should be easy to find by noting modifications
	to .h files in the log command above. And more specifically,
	the following command will show each patch that has changed a
	public header file since the given version:

		find src/ -name '*.h' ! -name '*-private.h' \
		  ! -name 'cairoint.h' ! -name 'cairo-*features*.h' | \
		xargs git diff ${LAST_RELEASE}.. --

	Include a link to the incremental ChangeLog for this release,
	which we'll be uploading in a later step:

		https://cairographics.org/releases/ChangeLog.cairo-${THIS_RELEASE}

4) Increment cairo_version_{minor|micro} in cairo-version.h:

	If there are backward-incompatible changes in the API, stop
	now and don't release. Go back and fix the API instead. Cairo
	is intended to remain backwards-compatible as far as API.

	So cairo_version_major will not be incremented unless we come
	up with a new versioning scheme to take advantage of it.

	If there are API additions, then increment cairo_version_minor
	and reset cairo_version_micro to 0. NOTE: The minor version is
	only incremented for releases, not for snapshots.

	Otherwise, (i.e. there are only bug fixes), increment
	cairo_version_micro to the next larger (even) number.

5) For Minor releases, add an index entry to doc/public/cairo-docs.xml

        Towards the end of the file, add a new section for the stable
	release.  It'll look something like:

	<index id="index-X.Y" role="X.Y">
	  <title>Index of new symbols in X.Y</title>
	</index>

6) Commit the changes to NEWS and cairo-version.h

	It's especially important to mention the new version number in your
	commit log.

7) Run "make release-publish" which will perform the following steps
   for you:

	* Generate ChangeLog files out of git repository
	* Check that ChangeLog files were generated properly
	* Check that the version number ends with an even micro component
	* Check that no release exists with the current version
	* Verify that make distcheck 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 https://cairographics.org/releases
	* Generate a versioned manual and upload it to appear as both:
	  https://cairographics.org/manual-${THIS_RELEASE}
	  https://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 ${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.)
	* 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.

	Upload the incremental ChangeLog generated by the above:

		scp ChangeLog.cache-${LAST_RELEASE}.. \
		    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 ${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}.

8) Push the new tag out to the central tree with a command like:

	git push origin master ${THIS_RELEASE}

9) Update master (or the stable branch) version number.

	For Micro releases (X.Y.Z+2), increment cairo_version_micro to
	the next larger (odd) number in cairo-version.h, commit, and
	push.

		DEVEL_VERSION="X.Y.Z+1"  # e.g. 1.15.10 -> 1.15.11

	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.

	       DEVEL_VERSION="X.Y.Z+1"  # e.g. 1.16.0 -> 1.17.1

	git commit cairo-version.h -m "Bump version for ${DEVEL_VERSION}"

10) Edit the cairo bugzilla product and add the new version numbers.

	Note that you need to add two versions.  One for the
	release/snapshot (with an even micro version), another with the
	post-release version (with an odd micro version).

11) Send out an announcement message.

	Send a message to cairo-announce@cairographics.org and CC
	cairo@cairographics.org, gnome-announce-list@gnome.org and
	ftp-release@lists.freedesktop.org (pr@lwn.net as well for major
	releases) to announce the new release using the text provided from
	"make release-publish", adding the excerpt from NEWS and
	the shortlog of all changes since last release, generated by:

		git shortlog ${LAST_RELEASE}...

12) Add the announcement to the website as a new entry in the news/
    dir.  It will automatically get indexed onto the homepage when the
    site refreshes.