path: root/doc/releases.md

---
Copyright: © 2021 SANE Project
SPDX-License-Identifier: CC-BY-SA-4.0
---

# Creating A New `sane-backends` Release

This file summarizes most points to pay attention to when planning for
a new `sane-backends` release.  Content has been checked while working
on `$old_version` and getting ready for `$new_version`, where:

``` sh
old_version=1.0.31
new_version=1.0.32
```

## Timetable

It is easiest to pick a release date well in advance so everyone knows
what to expect.  Ignoring security bug fix releases, `sane-backends`
has been released on a roughly half-yearly schedule since `1.0.28`.

Once you pick a date (and time), say `DT`, the planning is simply a
matter of counting back from there:

 - `$DT -  0 days`: **release** :confetti_ball:
 - `$DT - 21 days`: **branch off** after which the release branch will not get any new features,
   only bug fixes and translations.
 - `$DT - 35 days`: **schedule announcement** including the timetable.

Feel free to adjust the offsets if that works better.  Also, pinging
on the mailing list well in advance, say two, three months, about a
suitable date for everyone involved is a good idea.

> If you mention time of day, on the mailing list, in issues or merge
> requests, use UTC times and mention that, e.g. 09:00 UTC.  People
> are in time zones all over the place and converting to and from UTC
> should be relatively easy for everyone.  Converting from other
> time zones is generally cumbersome, even without things like DST.

## Schedule Announcement

Send an announcement to the `sane-devel` mailing list announcing the schedule.

All notable changes are tracked as separate files in the newsfragments directory which means there's
no need to track them manually.

## Branch off

A separate branch for the upcoming release is created on the repository. This marks the point when
the code for the release effectively enters a feature freeze and no new features will land into
the release branch.

Use branch in the format of `release-1.2.x` so that it's clear that further bugfix releases will
happen on that branch.

Notify `sane-devel` of the Branch Off and point out that merge requests that have to be included
in the upcoming release need to be targeted at release branch. Anything else can go to `master` as
usual.

For backends added since the `$old_version`, make sure that its
`.desc` file includes a `:new :yes` near the top.  You can find such
backends from the list of added files with:

``` sh
git ls-files -- backend | while read f; do
  git log --follow --diff-filter=A --find-renames=40% \
          --format="%ai  $f" $old_version..release/$new_version -- "$f"
done | cat
```

Feature changes are no longer allowed, bar exceptional circumstances, so now is a good time to
sync the `po/*.po` files in the repository for translators.

Announce the Branch Off on `sane-devel` and invite translators to contribute their updates.
Release manager should ensure that whichever branch the translator work on, their work lands on
both the release branch and the master branch.

Occasionally, you may notice changes that have not been documented,
either in a `.desc` file or a manual page.  Now is a good time to
rectify the omission.

The `NEWS` file is updated during the release time, there's no need to do anything with the
release notes now.

## Release

The release consists of two parts: a release notes MR and the actual release.

The release notes are handled by the towncrier tool. The easiest way to use it is from virtualenv:

``` sh
virtualenv some/path/to/virtualenv
source some/path/to/virtualenv
pip install towncrier
```

To update the `NEWS `document, run the following:

```
towncrier --version $new_version --date `date -u  +%F`
```

After that, create a new MR, merge it and fetch the new release branch.

The actual release is as easy as pushing a tag and clicking a web UI button.  GitLab CI/CD
takes care of the rest.

``` sh
git tag -a -s $new_version -m "Release $new_version"
git push --tags origin release-$new_release
```

The final job in the release pipeline that is triggered by the above
is a manual job.  You have to press a button in the web UI.  However,
before you do so, create a Personal Access Token (with `api` scope) in
your own GitLab account's `Settings` > [`Access Tokens`][] and use its
value to set the `PRIVATE_TOKEN` variable for the `upload` job in the
`Release` stage.  You need to set this on the page that triggers the
`upload` job.

 [`Access Tokens`]: https://gitlab.com/-/profile/personal_access_tokens
 [`CI/CD`]: https://gitlab.com/sane-project/backends/-/settings/ci_cd

### Updating The Website

After the release artifacts, i.e. the source tarball, have hit the
GitLab [Release][] tab, grab the source tarball to create updated
lists of supported devices and HTML manual pages for the website.

With the `$new_version`'s source tarball:

``` sh
tar xaf sane-backends-$new_version.tar.gz@
cd sane-backends-$new_version
./configure
make -C lib
make -C sanei
make -C doc html-pages
LANG=C make -C doc html-man
```

The last command assumes you have `man2html` in your `$PATH`.  There
are various versions of this command but `make` assumes you are using
the version from one of:

- https://savannah.nongnu.org/projects/man2html/
- https://web.archive.org/web/20100611002649/http://hydra.nac.uci.edu/indiv/ehood/tar/man2html3.0.1.tar.gz

Using anything else is asking for trouble.

> See also #261.

With the various HTML pages generated in `sane-backends-$new_version`,
check out the latest code of the sane-project/website and:

``` sh
cd website
rm man/*
cp .../sane-backends-$new_version/doc/*.[1578].html man/
git add man/
git mv sane-backends.html sane-backends-$old_version.html
cp .../sane-backends-$new_version/doc/sane-{backends,mfgs}.html .
git add sane-{backends,mfgs}.html
```

Next, add a hyperlink to the `$old_version`'s file in
`sane-supported-devices.html` and add an entry for the new release to
`index.html`.

Finally

``` sh
git add sane-supported-devices.html index.html
git commit -m "Update for sane-backends-$new_version release"
git push
```

The push will trigger a GitLab CI/CD pipeline that will update the
website.  Make sure it succeeds (see sane-project/website#33 for one
reason it might fail).

 [Release]: https://gitlab.com/sane-project/backends/-/releases

### Mailing List Announcement

Once the website has been updated successfully, announce the release
on the `sane-announce` mailing list (and Cc: `sane-devel`).  You may
want to ping the `sane-announce` list's moderator (@kitno455) to get
your post approved sooner rather than later.

## Post-Release

With the release all done, there are still a few finishing touches that need taking care of:

* remove the `:new` tag from all `doc/descriptions*/*.desc` files
* update this file!

That's All Folks!