2021-02-16 11:30:46 +00:00
|
|
|
---
|
|
|
|
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:
|
2022-01-18 20:12:19 +00:00
|
|
|
- `$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.
|
2021-02-16 11:30:46 +00:00
|
|
|
|
|
|
|
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
|
|
|
|
|
2022-01-18 20:12:19 +00:00
|
|
|
Send an announcement to the `sane-devel` mailing list announcing the schedule.
|
2021-02-16 11:30:46 +00:00
|
|
|
|
2022-01-18 20:12:19 +00:00
|
|
|
All notable changes are tracked as separate files in the newsfragments directory which means there's
|
|
|
|
no need to track them manually.
|
2021-02-16 11:30:46 +00:00
|
|
|
|
2022-01-18 20:12:19 +00:00
|
|
|
## Branch off
|
2021-02-16 11:30:46 +00:00
|
|
|
|
2022-01-18 20:12:19 +00:00
|
|
|
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.
|
2021-02-16 11:30:46 +00:00
|
|
|
|
2022-01-18 20:12:19 +00:00
|
|
|
Use branch in the format of `release-1.2.x` so that it's clear that further bugfix releases will
|
|
|
|
happen on that branch.
|
2021-02-16 11:30:46 +00:00
|
|
|
|
2022-01-18 20:12:19 +00:00
|
|
|
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.
|
2021-02-16 11:30:46 +00:00
|
|
|
|
|
|
|
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
|
|
|
|
```
|
|
|
|
|
2022-01-18 20:12:19 +00:00
|
|
|
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.
|
2021-02-16 11:30:46 +00:00
|
|
|
|
2022-01-18 20:12:19 +00:00
|
|
|
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.
|
2021-02-16 11:30:46 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2022-01-18 20:12:19 +00:00
|
|
|
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:
|
2021-02-16 11:30:46 +00:00
|
|
|
|
|
|
|
``` sh
|
2022-01-18 20:12:19 +00:00
|
|
|
virtualenv some/path/to/virtualenv
|
|
|
|
source some/path/to/virtualenv
|
|
|
|
pip install towncrier
|
2021-02-16 11:30:46 +00:00
|
|
|
```
|
|
|
|
|
2022-01-18 20:12:19 +00:00
|
|
|
To update the `NEWS `document, run the following:
|
2021-02-16 11:30:46 +00:00
|
|
|
|
2022-01-18 20:12:19 +00:00
|
|
|
```
|
|
|
|
towncrier --version $new_version --date `date -u +%F`
|
|
|
|
```
|
|
|
|
|
|
|
|
After that, create a new MR, merge it and fetch the new release branch.
|
2021-02-16 11:30:46 +00:00
|
|
|
|
2022-01-18 20:12:19 +00:00
|
|
|
The actual release is as easy as pushing a tag and clicking a web UI button. GitLab CI/CD
|
2021-02-16 11:30:46 +00:00
|
|
|
takes care of the rest.
|
|
|
|
|
|
|
|
``` sh
|
2022-01-18 20:12:19 +00:00
|
|
|
git tag -a -s $new_version -m "Release $new_version"
|
|
|
|
git push --tags origin release-$new_release
|
2021-02-16 11:30:46 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
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
|
|
|
|
|
2022-01-18 20:12:19 +00:00
|
|
|
With the release all done, there are still a few finishing touches that need taking care of:
|
2021-02-16 11:30:46 +00:00
|
|
|
|
|
|
|
* remove the `:new` tag from all `doc/descriptions*/*.desc` files
|
|
|
|
* update this file!
|
|
|
|
|
|
|
|
That's All Folks!
|