Release process checklist
=========================

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; push a branch.
-  ☐ Create a merge request; fix it until it passes the CI.  Merge it.
-  ☐ Create a signed tag for the merge commit - ``git tag -s x.y.z`` with the version number.
-  ☐ ``git push`` the signed tag to gitlab.gnome.org/GNOME/librsvg
-  ☐ Go to the merge request's pipeline, and look for the ``distcheck`` job.  That one has the release tarball; download it.
-  ☐ Copy that tarball to the FTP staging server: ``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, 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``.

-  ☐ 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 and release schedule
------------------------------------

``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 `GNOME's release versioning as of 2022/September
<https://discourse.gnome.org/t/even-odd-versioning-is-confusing-lets-stop-doing-it/10391>`_.
(Note that it used an even/odd numbering scheme before librsvg 2.55.x)

Librsvg follows `GNOME's six-month release schedule
<https://wiki.gnome.org/ReleasePlanning>`_.

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 GNOME releases. File an
issue in their `repository
<https://gitlab.gnome.org/GNOME/releng/-/issues>`__ to indicate that
the new ``librsvg-x.y.0`` is a stable 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.

Please update all of these values when increasing the MSRV:

- ``MININUM_RUST_VER`` in ``configure.ac``.

- ``rust-version`` in ``Cargo.toml``.

- ``RUST_MINIMUM`` in ``ci/container_builds.yml``.

- The ``_manual_setup`` section in ``devel-docs/devel_environment.rst``.

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.
