Move the RELEASING.md document to the development guide

Part-of: <https://gitlab.gnome.org/GNOME/librsvg/-/merge_requests/735>

2 files changed, 241 insertions, 1 deletions

diff --git a/devel-docs/index.rst b/devel-docs/index.rst
index a5b2af8c..e9084d26 100644
--- a/devel-docs/index.rst
+++ b/devel-docs/index.rst
@@ -12,6 +12,7 @@ Development guide for librsvg
    ci
    text_layout
    api_observability
+   releasing
    :maxdepth: 1
    :caption: Contents:
 
@@ -74,7 +75,7 @@ contributions.
 Information for maintainers
 ---------------------------
 
-FIXME: Move RELEASING.md here
+- :doc:`releasing`
 
 Overview of the maintainer's workflow.
 
diff --git a/devel-docs/releasing.rst b/devel-docs/releasing.rst
new file mode 100644
index 00000000..d17d3a0c
--- /dev/null
+++ b/devel-docs/releasing.rst
@@ -0,0 +1,239 @@
+Release process checklist for librsvg
+=====================================
+
+Feel free to print this document or copy it to a text editor to check
+off items while making a release.
+
+-  ☐ Refresh your memory with
+   https://wiki.gnome.org/MaintainersCorner/Releasing
+-  ☐ Increase the package version number in ``configure.ac`` (it may
+   already be increased but not released; double-check it).
+-  ☐ Copy version number to ``Cargo.toml``.
+-  ☐ Copy version number to ``doc/librsvg.toml``.
+-  ☐ ``cargo update`` - needed because you tweaked ``Cargo.toml``, and
+   also to get new dependencies.
+-  ☐ Tweak the library version number in ``configure.ac`` if the API
+   changed; follow the steps there.
+-  ☐ Update ``NEWS``, see below for the preferred format.
+-  ☐ Commit the changes above.
+-  ☐ Make a tarball with
+   ``./autogen.sh --enable-vala && make distcheck DESTDIR=/tmp/foo`` -
+   fix things until it passes.
+-  ☐ Create a signed tag - ``git tag -s x.y.z`` with the version number.
+-  ☐ ``git push`` to the appropriate branch to
+   gitlab.gnome.org/GNOME/librsvg
+-  ☐ ``git push`` the signed tag to gitlab.gnome.org/GNOME/librsvg
+-  ☐ ``scp librsvg-x.y.z.tar.xz master.gnome.org:``
+-  ☐ ``ssh master.gnome.org`` and then
+   ``ftpadmin install librsvg-x.y.z.tar.xz``
+-  ☐ Create a `release in Gitlab <https://gitlab.gnome.org/GNOME/librsvg/-/releases>`_.
+
+For ``x.y.0`` releases, at least, do the following:
+
+-  ☐ `Notify the release
+   team <https://gitlab.gnome.org/GNOME/releng/-/issues>`__ on whether
+   to use this ``librsvg-x.y.0`` for the next GNOME version via an issue
+   on their ``GNOME/releng`` project.
+
+-  ☐ ``cargo-audit audit`` and ensure we don’t have vulnerable
+   dependencies.
+
+Gitlab release
+--------------
+
+-  ☐ Go to https://gitlab.gnome.org/GNOME/librsvg/-/releases and click
+   the **New release** button.
+
+-  ☐ Select the tag ``x.y.z`` you created as part of the release steps.
+
+-  ☐ If there is an associated milestone, select it too.
+
+-  ☐ Fill in the release title - ``x.y.z - stable`` or
+   ``x.y.z - development``.
+
+-  ☐ Copy the release notes from NEWS.
+
+-  ☐ Add a release asset link to
+   ``https://download.gnome.org/sources/librsvg/x.y/librsvg-x.y.z.tar.xz``
+   and call it ``librsvg-x.y.z.tar.xz - release tarball``.
+
+-  ☐ Add a release asset link to
+   ``https://download.gnome.org/sources/librsvg/x.y/librsvg-x.y.z.sha256sum``
+   and call it
+   ``librsvg-x.y.z.sha256sum - release tarball       sha256sum``.
+
+Version numbers
+---------------
+
+``configure.ac`` and ``Cargo.toml`` must have the same **package
+version** number - this is the number that users of the library see.
+
+``configure.ac`` is where the **library version** is defined; this is
+what gets encoded in the SONAME of ``librsvg.so``.
+
+Librsvg follows an even/odd numbering scheme for the **package
+version**. For example, the 2.50.x series is for stable releases, and
+2.51.x is for unstable/development ones. The
+`release-team <https://gitlab.gnome.org/GNOME/releng/-/issues>`__ needs
+to be notified when a new series comes about, so they can adjust their
+tooling for the stable or development GNOME releases. File an issue in
+their `repository <https://gitlab.gnome.org/GNOME/releng/-/issues>`__ to
+indicate whether the new ``librsvg-x.y.0`` is a stable or development
+series.
+
+Minimum supported Rust version (MSRV)
+-------------------------------------
+
+While it may seem desirable to always require the latest released
+version of the Rust toolchain, to get new language features and such,
+this is really inconvenient for distributors of librsvg which do not
+update Rust all the time. So, we make a compromise.
+
+The ``configure.ac`` script defines ``MININUM_RUST_MAJOR`` and
+``MINIMUM_RUST_MINOR`` variables with librsvg’s minimum supported Rust
+version (MSRV). These ensure that distros will get an early failure
+during a build, at the ``configure`` step, if they have a version of
+Rust that is too old — instead of getting an obscure error message from
+``rustc`` in the middle of the build when it finds an unsupported
+language construct.
+
+As of March 2021, Cargo does not allow setting a minimum supported Rust
+version; you may want to keep an eye on `the MSRV
+RFC <https://github.com/rust-lang/rfcs/pull/2495>`__.
+
+Sometimes librsvg’s dependencies update their MSRV and librsvg may need
+to increase it as well. Please consider the following before doing this:
+
+-  Absolutely do not require a nightly snapshot of the compiler, or
+   crates that only build on nightly.
+
+-  Distributions with rolling releases usually keep their Rust
+   toolchains fairly well updated, maybe not always at the latest, but
+   within two or three releases earlier than the latest. If the MSRV you
+   want is within about six months of the latest, things are probably
+   safe.
+
+-  Enterprise distributions update more slowly. It is useful to watch
+   for the MSRV that Firefox requires, although sometimes Firefox
+   updates Rust very slowly as well. Now that distributions are shipping
+   packages other than Firefox that require Rust, they will probably
+   start updating more frequently.
+
+Generally — two or three releases earlier than the latest stable Rust is
+OK for rolling distros, probably perilous for enterprise distros.
+Releases within a year of an enterprise distro’s shipping date are
+probably OK.
+
+If you are not sure, ask on the `forum for GNOME
+distributors <https://discourse.gnome.org/tag/distributor>`__ about
+their plans! (That is, posts on ``discourse.gnome.org`` with the
+``distributor`` tag.)
+
+Format for release notes in NEWS
+--------------------------------
+
+The ``NEWS`` file contains the release notes. Please use something
+close to this format; it is not mandatory, but makes the formatting
+consistent, and is what tooling expects elsewhere - also by writing
+Markdown, you can just cut&paste it into a Gitlab release. You can skim
+bits of the ``NEWS`` file for examples on style and content.
+
+New entries go at the **top** of the file.
+
+::
+
+   Version x.y.z
+   =============
+
+   Commentary on the release; put anything here that you want to
+   highlight.  Note changes in the build process, if any, or any other
+   things that may trip up distributors.
+
+   ## Description of a special feature
+
+   You can include headings with `##` in Markdown syntax.
+
+   Blah blah blah.
+
+
+   Next is a list of features added and issues fixed; use gitlab's issue
+   numbers. I tend to use this order: first security bugs, then new
+   features and user-visible changes, finally regular bugs.  The
+   rationale is that if people stop reading early, at least they will
+   have seen the most important stuff first.
+
+   ## Changes:
+
+   - #123 - title of the issue, or short summary if it warrants more
+     discussion than just the title.
+
+   - #456 - fix blah blah (Contributor's Name).
+
+   ## Special thanks for this release:
+
+   - Any people that you want to highlight.  Feel free to omit this
+     section if the release is otherwise unremarkable.
+
+Making a tarball
+----------------
+
+::
+
+   make distcheck DESTDIR=/tmp/foo
+
+The ``DESTDIR`` is a quirk, required because otherwise the gdk-pixbuf
+loader will try to install itself into the system’s location for pixbuf
+loaders, and it won’t work. The ``DESTDIR`` is what Linux distribution
+packaging scripts use to ``make install`` the compiled artifacts to a
+temporary location before building a system package.
+
+Copying the tarball to master.gnome.org
+---------------------------------------
+
+If you don’t have a maintainer account there, ask federico@gnome.org to
+do it or `ask the release
+team <https://gitlab.gnome.org/GNOME/releng/-/issues>`__ to do it by
+filing an issue on their ``GNOME/releng`` project.
+
+Rust dependencies
+-----------------
+
+Librsvg's `Cargo.lock` is checked into git because the resolved
+versions of crates that it mentions are the ones that were actually
+used to run the test suite automatically in CI, and are "known good".
+In other words: `keep the results of dependency resolution in version
+control, and update those results manually
+<https://blog.ometer.com/2017/01/10/dear-package-managers-dependency-resolution-results-should-be-in-version-control/>`_.
+
+It is important to keep these dependencies updated; you can do that
+regularly with the ``cargo update`` step listed in the checklist
+above.
+
+`cargo-audit <https://github.com/RustSec/cargo-audit>`__ is very
+useful to scan the list of dependencies for registered vulnerabilities
+in the `RustSec vulnerability database <https://rustsec.org/>`__. Run
+it especially before making a new ``x.y.0`` release.
+
+Sometimes cargo-audit will report crates that are not vulnerable, but
+that are unmaintained. Keep an eye of those; you may want to file bugs
+upstream to see if the crates are really unmaintained or if they should
+be substituted for something else.
+
+Creating a stable release branch
+--------------------------------
+
+-  Create a branch named ``librsvg-xx.yy``, e.g. ``librsvg-2.54``
+
+-  Make the ``BASE_TAG`` in ``ci/container-builds.yml`` refer to the new
+   ``librsvg-xx.yy`` branch instead of ``main``.
+
+-  Push that branch to origin.
+
+-  (Branches with that naming scheme are already automatically protected
+   in gitlab’s Settings/Repository/Protected branches.)
+
+-  Edit the badge for the stable branch so it points to the new branch:
+   Settings/General/Badges, find the existing badge for the stable
+   branch, click on the edit button that looks like a pencil. Change the
+   **Link** and **Badge image URL**; usually it is enough to just change
+   the version number in both.