kopia lustrzana https://gitlab.com/sane-project/backends
Merge branch 'update-release-documentation' into 'master'
Update release documentation See merge request sane-project/backends!596261-fix-manual-page-to-html-conversion
Olaf Meeuwissen
commit
13d1cb694e
3
NEWS
3
NEWS
|
|
@ -1,5 +1,8 @@
|
||||||
<!-- -*- Mode: markdown -*- -->
|
<!-- -*- Mode: markdown -*- -->
|
||||||
|
|
||||||
|
## UNRELEASED
|
||||||
|
|
||||||
|
|
||||||
## New with 1.0.32 (released 2021-02-14)
|
## New with 1.0.32 (released 2021-02-14)
|
||||||
|
|
||||||
### Backends
|
### Backends
|
||||||
|
|
|
||||||
|
|
@ -86,7 +86,7 @@ all: bemans html-pages
|
||||||
|
|
||||||
dist_doc_DATA = backend-writing.txt
|
dist_doc_DATA = backend-writing.txt
|
||||||
nobase_dist_doc_DATA = $(BEDOCS)
|
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
|
sane.png
|
||||||
|
|
||||||
MAN2HTML = nroff -c -man |\
|
MAN2HTML = nroff -c -man |\
|
||||||
|
|
|
||||||
|
|
@ -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!
|
||||||
|
|
@ -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
|
|
||||||
Ładowanie…
Reference in New Issue