This document provides a step-by-step list to remind Orca
maintainers how to make a release.

The general instructions for a release are here:

  https://handbook.gnome.org/maintainers/making-a-release.html

Here's a summary for Orca:

PREPARE SOURCES FOR THE RELEASE:
-------------------------------

Make sure you are up to date:

  git pull
  git status

Run the `generate_gsettings_documentation.py` and `generate_dbus_documentation.py` tools.

Early in the release cycle, i.e. before string freeze, run the `generate_braille_table_names.py`
tool to update `brltablenames.py`.

Update ./NEWS with changes from the last tagged release. You can use
commands like the following:

Detailed commits since the 48.beta tag:

  git log 48.beta..

Short list of translation changes with author names and files:

  git log 48.beta.. --grep translation --pretty=format:"%s - %an" --name-only

Quick-and-dirty formatted list of translation changes:

  git log 48.beta.. --grep translation --pretty=format:"%s,%an" --name-only |
    awk -F/ '/\.po/ {gsub("\\.po", "", $NF); printf(",%s",$NF); next;}
    {gsub("(Updated* |Add(ed)* | translation| help)", "", $0); printf("\n%s",$0);}' |
    awk -F, '!seen[$0]++ {if (NF == 3) printf("  %-15s %-25s %s\n", $3, $1, $2);}' |
    sort

Short list of non-translation commits:

  git log 48.beta.. --grep translation --invert-grep --pretty=format:" * %s%n"

NOTE: You should also make sure the external dependencies listed in
meson.build and README.md are accurate.

CHECK THE MATHCAT VERSION:
--------------------------

MathCAT (https://github.com/daisy/MathCAT) provides our math speech and
braille. We build it from the Python bindings, MathCATForPython
(https://github.com/daisy/MathCATForPython).

Orca keeps its own copy of the binding directly in subprojects/mathcat-py/:
Cargo.toml, Cargo.lock, build.rs, meson.build, and the one upstream source
file, src/lib.rs. There is no wrap and nothing is downloaded at build time, so
a `git pull` is all it takes for a build to pick up a new version: the build
always re-runs cargo, and the install wipes and re-extracts the rule files so
nothing stale lingers.

The MathCAT engine itself is a crates.io crate, pinned with `=X.Y.Z` in our
Cargo.toml; cargo fetches that exact crate. The full version list, including
the betas we use, is at https://crates.io/crates/mathcat/versions.

Cargo.lock records the exact version cargo picked for every library in the
build, so everyone who builds from main gets the same result. You do not
regenerate it by hand: cargo only rewrites it when Cargo.toml changes (the
version bump below), and it does so automatically during the next build. You
just commit the updated file.

To move to a newer MathCAT:

* Set the new version (for example 0.7.6-beta.5) in three places in our
  Cargo.toml: `version` under [package], `version` under
  [dependencies.mathcat], and the `version` inside the `mathcat = {...}` line
  under [build-dependencies].

* Compare our Cargo.toml against upstream's
  (https://github.com/daisy/MathCATForPython/blob/main/Cargo.toml). If its
  `edition` or `zip` line differs, make ours match. A newer edition can raise
  the minimum required rustc. Ignore differences that are only comments.

* Replace src/lib.rs with upstream's for the matching version
  (https://github.com/daisy/MathCATForPython/blob/main/src/lib.rs). We compile
  it directly, so it must match the crate we pin.

* If the X.Y.Z base changes (not just the beta suffix), also bump `version:`
  in our meson.build to that base (for example 0.7.6).

* Build, then commit the updated Cargo.lock together with your changes.

COMMIT RELEASE CHANGES AND TAG THE RELEASE, TRIGGERING A RELEASE BUILD:
-----------------------------------------------------------------------

git commit -a
git push
git tag -a -s 48.rc
git push origin 48.rc

BUMP THE VERSION:
-----------------

Modify this line in ./meson.build:

    version: '48.rc'

The major version (48) increments by 1 each new GNOME release cycle.
The minor version proceeds as follows: alpha, beta, rc, 0, 1, 2, 3, etc.

Modify ./README.md to make sure it has the right Orca version.

If this is a .0 release, modify this line in .gitlab/issue_templates/Default.md:

   *Note that versions prior to version XX.x are unsupported for non-critical issues.*

setting "XX" to the major release preceding this one.

git commit -a
git push
