diff options
Diffstat (limited to 'devel-docs/releasing.rst')
-rw-r--r-- | devel-docs/releasing.rst | 239 |
1 files changed, 239 insertions, 0 deletions
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. |