From 7ac30dced0b89396ca707129aa303dd17083b042 Mon Sep 17 00:00:00 2001 From: Olaf Meeuwissen Date: Tue, 16 Feb 2021 19:46:57 +0900 Subject: [PATCH 1/2] NEWS: Add placeholder for user-visible changes in the next release --- NEWS | 3 +++ 1 file changed, 3 insertions(+) diff --git a/NEWS b/NEWS index 10310f882..6f02ab8ee 100644 --- a/NEWS +++ b/NEWS @@ -1,5 +1,8 @@ +## UNRELEASED + + ## New with 1.0.32 (released 2021-02-14) ### Backends From 5d749ac796621c1b988e6302871c9facb135f1dc Mon Sep 17 00:00:00 2001 From: Olaf Meeuwissen Date: Tue, 16 Feb 2021 20:30:46 +0900 Subject: [PATCH 2/2] doc: Update the release procedure and convert to Markdown --- doc/Makefile.am | 2 +- doc/releases.md | 220 +++++++++++++++++++++++++++++++++++++++++++++++ doc/releases.txt | 62 ------------- 3 files changed, 221 insertions(+), 63 deletions(-) create mode 100644 doc/releases.md delete mode 100644 doc/releases.txt diff --git a/doc/Makefile.am b/doc/Makefile.am index 5cf301128..17ae02f62 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -86,7 +86,7 @@ all: bemans html-pages dist_doc_DATA = backend-writing.txt nobase_dist_doc_DATA = $(BEDOCS) -EXTRA_DIST += descriptions.txt releases.txt sane-logo2.jpg sane-logo.png \ +EXTRA_DIST += descriptions.txt releases.md sane-logo2.jpg sane-logo.png \ sane.png MAN2HTML = nroff -c -man |\ diff --git a/doc/releases.md b/doc/releases.md new file mode 100644 index 000000000..c39c7b1bf --- /dev/null +++ b/doc/releases.md @@ -0,0 +1,220 @@ +--- +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 - 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: + +``` 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 +``` + +## 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 + +``` sh +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 + +``` sh +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. + +``` sh +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. + + [`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* + +* 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! diff --git a/doc/releases.txt b/doc/releases.txt deleted file mode 100644 index 0cb751863..000000000 --- a/doc/releases.txt +++ /dev/null @@ -1,62 +0,0 @@ -2019-08-24 - -This text summarizes some points to pay attention to when a new release -of sane-backends is planned. - -Timetable (approximate periods): - -Day 0: Announcement of upcoming release on sane-devel including timetable - and pointer to the GitLab milestone -Day 14: Feature freeze (only bugfixes + documentation updates) -Day 28: Code freeze (only fixes for bugs that can destroy hardware, can cause - compilation problems or render a backend completely unusable, and - documentation updates are allowed) -Day 35: Release - -Before the release: - -* set :new :yes on any new backend .desc files, by looking for added files: - - version=1.0.27 - git ls-files -- backend | while read f; do - git log --follow --diff-filter=A --find-renames=40% \ - --format="%ai $f" $version..HEAD -- "$f" - done | cat - -* NEWS: update and enter date of release, etc - Get list of heavily change backends via: git diff --stat $version..HEAD - Get list of details from: git log $version..HEAD -* git commit -a -* git push origin master - -Making the release: - -* temporarily set a PRIVATE_TOKEN variable in the GitLab CI/CD - variables. You have to create one in your own Settings > Access - Tokens. Set it to expire the next day to avoid abuse. Better yet, - remove it from the CI/CD variables when the job is finished. -* git tag -a -s 1.0.28 -m Release -* git push --tags origin master -* trigger the manual 'release' stage of the build via the web UI when - this becomes possible. This requires a valid PRIVATE_TOKEN. - -Updating the website and announcing the release: - -* checkout the sane/website.git module and: -* copy sane-backends.html to sane-backends-"old-version".html -* update sane-supported-devices.html with link to above "old" file -* rebuild sane-backends.html and sane-mfgs.html (make -C doc html-pages) -* [TBD] use man2html from http://hydra.nac.uci.edu/indiv/ehood/man2html.html - to rebuild html man pages (make -C doc html-man) (no other version works) -* update announcement to index.html -* git commit -a && git push -* check that website's pipeline succeeded -* announce release on sane-announce mailing list (and Cc: sane-devel). - Ping the sane-announce list's moderator (m. allan noah) to get your - post approved ASAP. - -After the release: - -* remove the ':new' tag from all doc/descriptions*/*.desc files -* git add new and changed files and commit -* git push