docs: Update the release instructions

2 files changed, 126 insertions, 108 deletions

diff --git a/docs/RELEASE-HOWTO b/docs/RELEASE-HOWTO
deleted file mode 100644
index b3c66ac247..0000000000
--- a/docs/RELEASE-HOWTO
+++ /dev/null
@@ -1,108 +0,0 @@
-How to do a GTK+ release?
-=========================
-
-Make sure you have suitable versions of autoconf and libtool.
-Also make sure you have the following packages installed with all their
-dependencies:
-* gtk-doc
-* docbook-utils
-Without those packages make distcheck will *not* pass.
-Make sure that gtk-doc is the latest released version.
-
-
- 0) Go back to a pristine working directory. With git, this works:
-
-    git clean -f -x
-
- 1) autogen and build it, make sure to enable docs by specifying
-    --enable-gtk-doc --enable-man
-
- 2) Update NEWS based on the content of git log; follow the format
-    of prior entries. This includes finding noteworthy new features,
-    collecting summaries for all the fixed bugs that are referenced
-    and collecting all updated translations.
-    Also collect the names of all contributors that are mentioned.
-    We don't discriminate between bug reporters, patch writers,
-    committers, etc. Anybody who is mentioned in ChangeLog gets
-    credits, but only real names, not email addresses or nicknames.
-
- 3) Update the pot files and commit the changes:
-
-    make -C po gtk40.pot
-    make -C po-properties gtk40-properties.pot
-
- 4) In particular, if this is a major, stable, release, verify that
-    README.in contains the relevant release notes and that the
-    required versions of dependencies in INSTALL.in are in sync
-    with configure.ac.
-
- 5) Verify that the version in configure.ac has been bumped after the last
-    release. (Note that this is critical, a slip-up here will cause the
-    soname to change).
-
- 6) Make sure that make check is happy (If you don't do it here, make distcheck
-    will also catch it, but it is kind of disheartening to see make distcheck
-    fail due to an extraneous symbol after watching it build the docs for an
-    hour...).
-    Typical problems to expect here (depending on whether this is a devel
-    snapshot or a stable release):
-    * forgotten source files
-    * new symbols missing from .symbols files
-    * symbols that are exported by should be private (static or _-prefixed)
-    * symbols that cause PLT entries. This is either caused by using a function
-      in the same library function without including the header or by using a
-      function from a different library, which is not yet allowed by the filter
-      in pltcheck.sh
-
- 7) If this is a devel release, make sure that the docs for new symbols
-    are in good shape. Look at the -unused.txt files and add stuff found
-    there to the corresponding -sections.txt file. Look at the
-    -undocumented.txt files and see if there is anything in there that
-    should be documented. If it is, this may be due to typos in the doc
-    comments in the source. Make sure that all new symbols have proper
-    Since: tags, and that there is an index in the main -docs.sgml for
-    the next stable version.
-
- 8) make distcheck
-
- 9) Fix broken stuff found by 8), commit changes: git commit -a, repeat.
-
-10) Once distcheck succeeds, verify that the tree is clean: git diff should
-    come up empty.
-
-10) Now you've got the tarball. Check that the tarball size looks
-    reasonable compared to previous releases. If the size goes down
-    a lot, likely the docs went missing for some reason. Or the translations.
-    If the size goes up by a lot, something else may be wrong.
-
-11) Tag the release. The git command for doing that looks like
-
-    git tag -m "GTK+ 2.12.10" 2.12.10
-
-12) Push the tagged commit upstream. The git command for doing that is
-
-    git push origin refs/tags/2.12.10
-
-13) Bump the version number in configure.ac and commit and push this change
-
-14) Upload the tarball to master.gnome.org and run install-module to transfer
-    it to download.gnome.org. If you don't have an account on master.gnome.org,
-    find someone who can do it for you. The command for this looks like
-
-      scp gtk+-2.12.10.tar.xz matthiasc@master.gnome.org:
-      ssh matthiasc@master.gnome.org ftpadmin install gtk+-2.12.10.tar.xz
-
-15) Upload the tarball and checksum to ftp.gtk.org and put them in the right
-    directory below /ftp/pub. Pay attention to correct ownership, and don't
-    forget to update the LATEST file in the directory.
-
-16) Go to the gnome-announce list archives, find the last announce message,
-    create a new message in the same form, replacing version numbers,
-    commentary at the top about "what this release is about" and the
-    summary of changes.
-
-17) Send it to gnome-announce-list, gtk-list, gtk-app-devel-list and
-    gtk-devel-list. Set reply-to to desktop-devel-list.
-
-18) Add a link to the release announcement to www.gtk.org which lives
-    in the gtk-web git module.
diff --git a/docs/RELEASE-HOWTO.md b/docs/RELEASE-HOWTO.md
new file mode 100644
index 0000000000..c47d95fb3d
--- /dev/null
+++ b/docs/RELEASE-HOWTO.md
@@ -0,0 +1,126 @@
+How to do a GTK+ release?
+=========================
+
+## Before we begin
+
+Make sure you have suitable versions of Meson and Ninja.
+
+Also make sure you have the following packages installed with all their
+dependencies:
+
+  * gtk-doc
+  * docbook-utils
+
+Without those packages make distcheck will *not* pass.
+
+Make sure that gtk-doc is the latest released version.
+
+## Release check list
+
+  0. Save all your work, then move to the branch from which you want
+     to release. Go back to a pristine working directory. With Git,
+     this works:
+
+```sh
+$ git clean -dfx
+```
+
+  1. Build using the common sequence:
+
+```sh
+$ meson _build .
+$ ninja -C _build
+```
+
+  2. Update NEWS based on the content of git log; follow the format of prior
+     entries. This includes finding noteworthy new features, collecting
+     summaries for all the fixed bugs that are referenced and collecting all
+     updated translations. Also collect the names of all contributors that
+     are mentioned. We don't discriminate between bug reporters, patch
+     writers, committers, etc. Anybody who is mentioned in the commit log
+     gets a credit, but only real names, not email addresses or nicknames.
+
+  3. Update the pot files and commit the changes:
+
+```sh
+$ ninja -C _build gtk40-pot
+$ ninja -C _build gtk40-properties-pot
+```
+
+  4. If this is a major, stable, release, verify that the release notes
+     in the API reference contain the relevant items.
+
+  5. Verify that the version in `meson.build` has been bumped after the last
+     release. **Note**: this is critical, a slip-up here will cause the soname
+     to change.
+
+  6. Make sure that `mesontest` is happy (`ninja dist` will also run the test
+     suite, but it's better to catch issues before committing and tagging
+     the release). Typical problems to expect here (depending on whether this
+     is a devel  snapshot or a stable release):
+
+    * forgotten source files
+    * new symbols missing the `GDK_AVAILABLE_IN_` annotation
+    * wrong introspection annotations
+    * missing documentation
+
+  7. If this is a devel release, make sure that the docs for new symbols are
+     in good shape. Look at the -unused.txt files and add stuff found there
+     to the corresponding `-sections.txt` file. Look at the `-undocumented.txt`
+     files and see if there is anything in there that should be documented.
+     If it is, this may be due to typos in the doc comments in the source.
+     Make sure that all new symbols have proper Since: tags, and that there
+     is an index in the main `-docs.xml` for the next stable version.
+
+  8. Run `ninja dist` to generate the tarball.
+
+  9. Fix broken stuff found by 8), commit changes, repeat.
+
+  10. Once `dist` succeeds, verify that the tree is clean and all the changes
+     needed to make the release have been committed: `git diff` should come
+     up empty. The last commit must be the commit that bumps up the version
+     of the release in the `meson.build` file. Use `git rebase` if you had to
+     add more commits after the version bump and `dist` successfully passing.
+     If you change the history, remember to rebuild the tarball.
+
+  11. Now you've got the tarball. Check that the tarball size looks reasonable
+    compared to previous releases. If the size goes down a lot, likely the
+    docs went missing for some reason. Or the translations. If the size goes
+    up by a lot, something else may be wrong.
+
+  12. Tag the release. The git command for doing that looks like:
+
+```sh
+$ git tag -m "GTK+ 4.2.0" 4.2.0
+```
+
+  13. Bump the version number in `meson.build` and commit the change.
+
+  14. Push the changes upstream, and push the tag as well. The git command for
+    doing that is:
+
+```sh
+$ git push origin
+$ git push origin 4.2.0
+```
+
+  15. Upload the tarball to `master.gnome.org` and run `ftpadmin install` to
+    transfer it to `download.gnome.org`. If you don't have an account on
+    `master.gnome.org`, find someone who can do it for you. The command for
+    this looks like:
+
+```sh
+$ scp gtk+-4.2.0.tar.xz matthiasc@master.gnome.org:
+$ ssh matthiasc@master.gnome.org ftpadmin install gtk+-4.2.0.tar.xz
+```
+
+  16. Go to the gnome-announce list archives, find the last announce message,
+    create a new message in the same form, replacing version numbers,
+    commentary at the top about "what this release is about" and the
+    summary of changes.
+
+  17. Send it to gnome-announce-list, gtk-list, gtk-app-devel-list and
+    gtk-devel-list. Set reply-to to desktop-devel-list.
+
+  18. Add a link to the release announcement to www.gtk.org which lives
+    in the gtk-web git module.