docs: Update the release instruction

Mainly drop the Autotools-related stuff, and use Markdown.

1 files changed, 116 insertions, 156 deletions

diff --git a/doc/releasing.md b/doc/releasing.md
index 04c78e20a..ab5abb62b 100644
--- a/doc/releasing.md
+++ b/doc/releasing.md
@@ -1,215 +1,175 @@
-Here are the steps to follow to create a new cairo release:
+# Releasing Cairo
 
-0) Decide type of release and checkout the appropriate branch.
+Here are the steps to follow to create a new cairo release:
 
-	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.
+## 0. Decide type of release and checkout the appropriate branch
 
-	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".
+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.
 
-1) Ensure that there are no local, uncommitted/unpushed mods.
+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".
 
-	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).
+## 1. Ensure that there are no local, uncommitted/unpushed mods
 
-2) Verify that the code passes "make distcheck"
+You're probably in a good state if both "git diff HEAD" and "git log
+master..origin/master" give no output.
 
-	First, make sure you have 'nm' and 'readelf' commands in PATH.
-	this should be OK with any Linux distro.
+## 2. Verify that the code passes `meson dist`
 
-	Running "make distcheck" should result in no warnings or
-	errors and end with a message of the form:
+First, make sure you have 'nm' and 'readelf' commands in `PATH`.  this
+should be OK with any Linux distro.
 
-	=============================================
-	cairo-X.Y.Z archives ready for distribution:
-	cairo-X.Y.Z.tar.gz
-	=============================================
+Running "meson dist" should result in no warnings or errors and end with a
+message of the form:
 
-	(But the tar file isn't actually ready yet, as we still have
-	some more steps to follow).
+    Created source/cairo/_build/meson-dist/cairo-1.17.8.tar.xz
 
-	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 the test suite does not pass, you can use:
 
-	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.
+    meson dist --no-tests
 
-	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:
+But this should only be allowed for development snapshots. Please, always
+check the state of the CI pipeline on GitLab.
 
-		DISPLAY= CAIRO_TEST_TARGET=" "
+## 3. Decide what the new version number for the release will be.
 
-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:
 
-	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
 
-		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:
 
-	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
 
-		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.:
 
-	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
 
-		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:
 
-	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
 
-		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
 
-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:
 
-	Sift through the logs since the last release. This is most
-	easily done with a command such as:
+    git log --stat ${LAST_RELEASE}..
 
-		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:
 
-	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}.. --
+```
 
-		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:
+## 5. Increment `CAIRO_VERSION_{MINOR|MICRO}` in `src/cairo-version.h`:
 
-		https://cairographics.org/releases/ChangeLog.cairo-${THIS_RELEASE}
+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.
 
-4) Increment cairo_version_{minor|micro} in src/cairo-version.h:
+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 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.
+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.
 
-	So cairo_version_major will not be incremented unless we come
-	up with a new versioning scheme to take advantage of it.
+Otherwise, (i.e. there are only bug fixes), increment `CAIRO_VERSION_MICRO`
+to the next larger (even) number.
 
-	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.
+## 6. For Minor releases, add an index entry to `doc/public/cairo-docs.xml`
 
-	Otherwise, (i.e. there are only bug fixes), increment
-	cairo_version_micro to the next larger (even) number.
+Towards the end of the file, add a new section for the stable release.
+It'll look something like:
 
-5) For Minor releases, add an index entry to doc/public/cairo-docs.xml
+```xml
+<index id="api-index-X-Y">
+  <title>Index of new symbols in X.Y</title>
+  <xi:include href="xml/api-index-X.Y.xml"/>
+</index>
+```
 
-        Towards the end of the file, add a new section for the stable
-	release.  It'll look something like:
+## 7. Commit the changes to `NEWS` and `src/cairo-version.h`
 
-	<index id="index-X.Y" role="X.Y">
-	  <title>Index of new symbols in X.Y</title>
-	</index>
+It's especially important to mention the new version number in your commit
+log.
 
-6) Commit the changes to NEWS and src/cairo-version.h
+## 8. Generate the release archive
 
-	It's especially important to mention the new version number in your
-	commit log.
+The `meson dist` command will:
 
-7) Run "make release-publish" which will perform the following steps
-   for you:
+ * Generate the final tar file
+ * Generate an sha1sum file
 
-	* 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.
+Once you have the release archive you will need to:
 
-	Upload the incremental ChangeLog generated by the above.  For
-	minor stable releases, this is:
+ * 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).
 
-		scp ChangeLog \
-		    cairographics.org:/srv/cairo.freedesktop.org/www/releases/ChangeLog.cairo-${THIS_RELEASE}
+## 9. Update master (or the stable branch) version number.
 
-        for micro and snapshot releases, the command is:
+For Micro releases (X.Y.Z+2), increment `CAIRO_VERSION_MICRO` to the next
+larger (odd) number in `src/cairo-version.h`.
 
-		scp ChangeLog.cache-${LAST_RELEASE}.. \
-		    cairographics.org:/srv/cairo.freedesktop.org/www/releases/ChangeLog.cairo-${THIS_RELEASE}
+    DEVEL_VERSION="X.Y.Z+1"  # e.g. 1.15.10 -> 1.15.11
 
-	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}.
+For Minor releases (X.Y.0), increment `CAIRO_VERSION_MINOR` to the next
+larger (odd) number, and set `CAIRO_VERSION_MICRO` to 1.
 
-8) Push the new tag out to the central tree with a command like:
+    DEVEL_VERSION="X.Y.Z+1"  # e.g. 1.16.0 -> 1.17.1
 
-	git push origin master ${THIS_RELEASE}
+Then, commit:
 
-9) Update master (or the stable branch) version number.
+    git commit src/cairo-version.h -m "Bump version for ${DEVEL_VERSION}"
 
-	For Micro releases (X.Y.Z+2), increment cairo_version_micro to
-	the next larger (odd) number in src/cairo-version.h, commit, and
-	push.
+## 9. Push the new tag out
 
-		DEVEL_VERSION="X.Y.Z+1"  # e.g. 1.15.10 -> 1.15.11
+Use:
 
-	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.
+    git push --atomic origin master ${THIS_RELEASE}
 
-	       DEVEL_VERSION="X.Y.Z+1"  # e.g. 1.16.0 -> 1.17.1
+to ensure that both the tag and the latest changes in your tree are uploaded
+at the same time.
 
-	git commit src/cairo-version.h -m "Bump version for ${DEVEL_VERSION}"
+## 10. Send out an announcement message.
 
-10) Send out an announcement message.
+Send a message to cairo-announce@cairographics.org and CC
+cairo@cairographics.org, and ftp-release@lists.freedesktop.org (pr@lwn.net
+as well for major releases) to announce the release, adding the excerpt from
+NEWS and the shortlog of all changes since last release, generated by:
 
-	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}...
 
-		git shortlog ${LAST_RELEASE}...
+## 11. Add the announcement to the website
 
-11) 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.
+Add a new entry in the `news` directory.  It will automatically get indexed
+onto the homepage when the site refreshes.