Sounds good to me. I have attached an updated copy of doc/releases.md,
which contains some notes I made during the last release. There were a
number of missing or poorly documented steps.
allan
On Sun, Jan 21, 2024 at 2:34 PM Ralph Little <skelb...@gmail.com> wrote:
> Hi,
> So it looks like we will do a 1.3.0 release.
> I propose a fairly quick timeline since there isn't a lot of critical
> stuff waiting to go in it. The only thing that I am aware of is the
> longstanding problem for macOS USB support and I think we have a partial
> solution for that which should push them on.
>
> Allan did the release last time, and perhaps I can go through the process
> this time so that I am familiar. Are you OK with that Allan?
>
> 1) Code freeze: 1 week from now (28th January), I will create a release
> branch and MRs targeted for the release should target that branch. Anything
> else not intended for the release can still target master. I will send out
> an email asking for translations after regenerating po files. During this
> time, we will not normally accept functional enhancements but exceptions
> will be considered in an emergency or if it is very safe.
>
> 2) Release: 2 weeks later (11th February) we will cut the release. I will
> also do a PPA release for our Ubuntu users.
>
> Cheers,
> Ralph
>
--
"well, I stand up next to a mountain- and I chop it down with the edge of
my hand"
---
Copyright: © 2023 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.1.1
new_version=1.2.1
```
## 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 - 35 days`: **schedule announcement** including the timetable.
- `$DT - 21 days`: **feature freeze** branch, only bug fixes and translations allowed.
- `$DT - 14 days`: **code freeze** only translations allowed.
- `$DT - 0 days`: **release** :confetti_ball:
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
Part of the announcement of the release schedule is a request from translators
to update translations. You can make this easier on them, by syncing the po
files before the announcement:
make -C po update-po
git add po
git commit -m "Update po files for sane-backends-$new_version release"
git push
Send an announcement to the `sane-devel` mailing list announcing the schedule.
Make sure to request translators to checkout the current master branch, and
produce updates (preferably before feature freeze starts).
## Feature Freeze
A separate branch for the upcoming release is created in the repository. This marks the point when
the code for the release effectively enters a feature freeze and no new features will be added to
the release branch.
At this point, no new text strings are likely to get added to the release branch. That means that
po files should be stable, and it is a good idea to again sync the po files for translators. If
we do this before we make the branch, we will not have to repeat it in both the master and release
branches.
make -C po update-po
git add po
git commit -m "Update po files for sane-backends-$new_version release"
git push
Name the branch in the format of `release-1.2.x` so that it's clear that further bugfix releases
will happen on that branch.
Here, we create the local branch, send it to remote, and then set our local to track the remote:
``` sh
release_branch=release-1.2.x
git branch $release_branch
git checkout $release_branch
git push origin $release_branch
git branch -u origin/$release_branch
```
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_branch -- "$f"
done | cat
```
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.
Once you have finished your changes, update the remote copy of the release branch:
``` sh
release_branch=release-1.2.x
git branch $release_branch
git checkout $release_branch
git push origin $release_branch
git branch -u origin/$release_branch
```
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 branch. Anything else can go to `master` as
usual. Make sure to request translators to checkout the new release branch, and produce updates.
If other contributors are making updates to the remote release branch, you will need to update
your local copy:
``` sh
git checkout $release_branch
git fetch
git rebase
```
## Code Freeze
You do not need to make any changes here, but it might be a good idea to alert sane-devel when
you reach this date. Again, probably a good idea to give instructions to translators.
## Release Notes
The release consists of two parts: a release notes MR and the actual release.
Historically, the release notes were added to NEWS file by hand, using the following:
- add a new section for this release
- Get list of heavily changed backends via: git diff --stat $old_version..HEAD
- Get list of details from: git log $old_version..HEAD
- Get count of new scanner models supported by supported devices page from the last release
- Add anything noteworthy that changed in backend, frontend, build env, etc.
More recently, we've attempted to generate these using the towncrier tool. Though, we reverted
to the manual technique for 1.2.1.
If you want to try 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 the NEWS file is updated, create a new MR, merge it and fetch the new release branch.
(or, if you are old-fashioned, git commit -a, git push)
## The Release
The actual release is as easy as pushing a tag and clicking a web UI button. GitLab CI/CD
takes care of the rest. It will run through compiling, tarring, etc. After a few minutes
wait, you should be able to move on.
``` sh
git tag -a -s $new_version -m "Release $new_version"
git push --tags origin $release_branch
```
The final job in the release pipeline 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 copy its
value.
[`Access Tokens`]: https://gitlab.com/-/profile/personal_access_tokens
Now visit the projects CI/CD > Jobs page. You should see jobs for stage
compile, snapshot and release. The release job will say 'manual', the
others should be 'passed'.
Download a zip file of artifacts from the snapshot job, and unzip it.
Open, configure, build and install the included sane-backends tarball.
This is your last chance to notice problems in the release.
Click the 'manual' next to the release (upload) job. On the next page,
Add a variable, Key = `PRIVATE_TOKEN`, Value = your access token. Then
press the blue button (I had to do it twice).
You should now be able to visit our releases page, and see your work:
https://gitlab.com/sane-project/backends/-/releases
## 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
HTML manual pages for the website.
With the `$new_version`'s source tarball:
``` sh
tar xzf backends-$new_version.tar.gz
cd backends-$new_version
./autogen.sh
./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. You might need to update the first line of this script
to point to your installed copy of perl, usually /usr/bin/perl
> 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
git clone g...@gitlab.com:sane-project/website.git
cd website
cp -a .../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!
