2019-07-30

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 in a few hours to avoid abuse.
* 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.

Announcing the release:

* [TBD] checkout the sane/website.git module and:
* [TBD] copy sane-backends.html to sane-backends-"old-version".html
* [TBD] update sane-supported-devices.html with link to above "old" file
* [TBD] 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)
* [TBD] add md5 sum to sane-md5sums.txt
* [TBD] check and update platforms page (sane-support.html)
* add announcement to index.html
* git commit -a && git push
* check that website was updated automatically
* [TBD] rebuild descriptions.db (make -C doc descriptions.db)
* announce release on sane-devel and sane-announce mailing lists

After the release:

* [TBD] copy ChangeLog to ChangeLogs/ChangeLog-$version
* [TBD] start a new ChangeLog via git checkout ChangeLog
* [TBD] bump version number in tools/create-changelog.sh
* remove the ':new' tag from all doc/descriptions*/*.desc files
* git add new and changed files and commit
* git push