7.5 KiB

Czysty Wina Historia

Copyright	SPDX-License-Identifier
© 2021 SANE Project	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:

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 🎊
$DT - 7 days: code freeze after which only documentation changes are allowed. As an exception, critical issues, such as hardware destroying bugs, compile errors and completely unusable backends, may still be addressed.
$DT - 21 days: feature freeze after which only bug fixes and documentation changes are allowed.
$DT - 35 days: schedule announcement including the timetable and a pointer to the corresponding GitLab milestone.

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

Create a milestone on GitLab that shows the schedule. The milestone can be used to collect issues resolved and merge request merged to master that will be included in the $new_version and coordinate work leading up to the release.

Send an announcement to the sane-devel mailing list announcing the schedule and point to the milestone.

Add closed issues that triggered code changes and merge requests to the milestone so you get an idea of what has been added, fixed, changed or removed. This will serve as the input for the NEWS file, together with git log and git diff outputs.

Feature Freeze

New backends, support for new models and new bells and whistles for existing backends (and frontends) are no longer allowed so this is a good time to cut a release/$new_version branch from the latest public master and publish it on GitLab.

Notify sane-devel of the Feature Freeze and point out that merge requests that have to be included in the upcoming release need to be targeted at release/$new_version. 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:

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

Code Freeze

Code 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 Code Freeze on sane-devel and invite translators to contribute their updates.

Start creating the NEWS file section for the $new_version. You should now have a list of issues and merge requests to help you get started. The following commands may be helpful as well

git diff --stat $old_version..release/$new_version | sort -k3 -n
                        # sorted list of heavily modified files
git log $old_version..release/$new_version
git diff $old_version..release/$new_version    # nitty-gritty details

Note that po/*.po files normally see quite a lot of changes due to the inclusion of source code line numbers.

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.

Happy that NEWS covers everything? Then

git commit NEWS
git push origin release/$new_version

on the day of the release.

Release

Once release/$new_version contains everything that should go in, including the changes to the NEWS file, releasing sane-backends is as easy as pushing a tag and clicking a web UI button. GitLab CI/CD takes care of the rest.

git tag -a -s $new_version -m Release
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.

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:

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:

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:

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

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).

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*

merge release/$new_version to current master
remove the :new tag from all doc/descriptions*/*.desc files
add a new UNRELEASED section at top of the NEWS file
update this file!
and get those changes on the master branch

That's All Folks!

7.5 KiB Czysty Wina Historia

Creating A New sane-backends Release