# 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.

## Pre-work
- [ ] Release libipuz, if necessary.

## A week before releasing
- [ ] Refresh your memory with: https://handbook.gnome.org/maintainers/making-a-release.html
- [ ] Update the overview files (such as README.md) and any other
      devel docs that need updating.
- [ ] Update README.md 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 files for appstream. Make sure
      to validate the result, and check that they shows up in the
      about dialog
    - [ ] Use `flatpak run --command=flatpak-builder-lint
          org.flatpak.Builder appstream _build/data/$APPSTREAMFILE` to
          validate the metainfo files.
- [ ] Update all devel docs. `emacs docs/*md`

## Translations
- [ ] Make sure all source files are in `po/POTFILES.in`. This can be
      done with `intltool-update -m`. Add any missing files to
      `POTFILES.in` or `POTFILES.skip`
- [ ] Update `crosswords.pot`. This is done by running `meson compile
      -C _build crosswords-pot`
- [ ] Remind translators of upcoming release in [discourse](https://discourse.gnome.org/tag/i18n).
- [ ] Check status at [damned lies](https://l10n.gnome.org/module/Crosswords/)

*Wait a week for translations to come in.*

While waiting for translations, do the following:

## Update the puzzle-sets

## Update the word lists, if desired
- [ ] Instructions for that are in the
      [word-list-tools](https://gitlab.gnome.org/jrb/word-list-tools)
      repo.

## Test Flatpaks
- [ ] Update both the rust and python dependencies. See below for details.
- [ ] Update org.gnome.Crosswords.Devel.json and org.gnome.Crosswords.Editor.Devel.json
     - [ ] Use `flatpak run --command=flatpak-builder-lint
         org.flatpak.Builder manifest
         ./org.gnome.Crosswords.Devel.json` to validate the flatpak
         manifest. Do the editor too. This is a good spot check to
         test against manifest problems
     - [ ] Don't forget to update the GNOME runtime as well
- [ ] Test both flatpaks
- [ ] Test puzzle-set flatpaks too before releasing

*Once translations are in, continue the release process*

## Release the source
- [ ] Release libipuz first, if necessary. Update the requirement in
      meson.build as well.
- [ ] Update the date in both metainfo files!
- [ ] Increase the package version number in `meson.build` (it may
already be increased but not released; double-check 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).

(gitlab-release)=
## Gitlab release

- [ ] Go to https://gitlab.gnome.org/jrb/crosswords/-/releases 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 builds at https://flathub.org/builds/#/
* [ ] Merge with master
* [ ] Update the puzzle-sets


## Brag a little
* [ ] Blog, toot, and promote on TWIG

----

## Maintaining Requirements Files

There are two requirements for building the flatpaks and they need
updating occasionally.

### cargo-sources.json

If Cargo.toml has changed, you'll need to regenerate both Cargo.lock
and the json file. The Cargo.lock is updated simply by building
libipuz. cargo-sources.json can be regenerated with:

```shell
../flatpak-builder-tools/cargo/flatpak-cargo-generator.py  subprojects/libipuz/libipuz/rust/Cargo.lock  -o cargo-sources.json
```

### 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.  Inside
the container image, you should run:

```shell
./ci/update-python-requirements
```

:::{important}
You will have to uncomment the `FLATPAK_PIP_GENERATOR`
command to point to the local version.
:::

----

## 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

```markdown
=============
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.
```
