Release process checklist for Crosswords

Feel free to print this document or copy it to a text editor to check off items while making a release. In general, it’s good to start the release process a week before the actual release.

A week before beginning

  • [ ] Refresh your memory with

  • [ ] Update the overview files and any other devel docs that need updating.

  • [ ] Update with any changes. Don’t forget to update the version number!

  • [ ] Rebuild with development off: meson setup _build/ --reconfigure -Ddevelopment=false

  • [ ] Do some final testing:

  • [ ] Go through outstanding issues! Make sure we’re ready to go and not forgetting something.

  • [ ] Make sure we pass all tests! ninja test -C _build

  • [ ] Run through manual tests

  • [ ] Update screenshots in data/images/ with updated versions

  • [ ] Update NEWS, see below for the preferred format and hints.

  • [ ] Copy the NEWS into the metainfo file for appstream. Make sure to validate the result.

  • [ ] Copy the NEWS into crosswords-credits.c file for the about dialog. Make sure to compile the result.


  • [ ] Make sure all source files are in po/POTFILES. This can be done with ls data/* puzzle-sets/{add*,uri}/*.in src/*{c,.ui}|cat|sort > po/POTFILES results

  • [ ] Update the po/pot files: meson compile -C _build crosswords-update-po

  • [ ] Remind translators of upcoming release. The news strings will have changed

  • [ ] File a bug to ask them to update translations

Wait a week for translations to come in.

Update the Peter Broda word list

  • [ ] Go to and grab the full scored, grid text file

  • [ ] Replace the wordlist in src/data/peter-broda-wordlist__full-text__scored.txt

  • [ ] Commit the file. It will build automatically next rebuild.

Release the source

  • [ ] Release libipuz first, if necessary. Update the requirement in as well.

  • [ ] Update the date in both metainfo files!

  • [ ] Increase the package version number in (it may already be increased but not released; double-check it).

  • [ ] Update org.gnome.Crosswords.Devel.json and test it

  • [ ] Commit the changes above.

  • [ ] Build it one more time

  • [ ] Create a release with meson dist in the _build directory. This won’t work if there are uncommitted changes.

  • [ ] Create a signed tag: git tag -s x.y.z with the version number.

  • [ ] git push origin master

  • [ ] git push origin x.y.z the signed tag

  • [ ] Create a release in Gitlab.

Gitlab release

  • [ ] Go to and click the New release button.

  • [ ] Select the tag x.y.z you created as part of the release steps.

  • [ ] If there is an associated milestone, select it too.

  • [ ] Fill in the release title - x.y.z - stable or x.y.z - development.

  • [ ] Copy the release notes from NEWS.

Update Flathub

  • [ ] Update the manifest in the flathub repo to point to the new tag.

  • [ ] Test the manifest locally: flatpak-builder --force-clean     _flatpak/ org.gnome.Crosswords.json

  • [ ] Push the new version to the beta branch upstream

  • [ ] Make sure the new version built at

  • [ ] Merge with master

  • [ ] Update the puzzle-sets

Brag a little

  • [ ] Blog, tweet, or promote on TWIG

Maintaining requirements.txt and python3-requirements.json

When python requirements change, update requirements.txt to match. You will also have to rebuild the requirements file for flatpaks by running:

~/Projects/flatpak-builder-tools/pip/flatpak-pip-generator  --requirements-file=requirements.txt -o python3-requirements

IMPORTANT: The generated file won’t build lxml within flatpaks as it’s included in the SDK. As a result, we have to hand-edit the pip3 install line for lxml to include the --ignore-installed.

Format for release notes in NEWS

The NEWS file contains the release notes. Please use something close to this format; it is not mandatory, but makes the formatting consistent, and is what tooling expects elsewhere - also by writing Markdown, you can just cut&paste it into a Gitlab release. You can skim bits of the NEWS file for examples on style and content.

New entries go at the top of the file.

An easy way to double check you got all the news is to run git log x.y.z..@ --oneline, where x.y.z is the last release tag.

Example News

Version x.y.z

Release date: Month xx, 20xx

Optional Summary

## Changes: Crosswords x.y.z
* Update 1
* Update 2
* Update 3

## Changes: Crossword Editor x.y.z
* Update 1

## Special thanks for this release:

- Any people that you want to highlight.