Releasing Sidekicks

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

# Releasing Sidekicks

[Français](RELEASING.fr.md)

Three steps, on the Mac: build everything, tag, attach the files; then bring the tag back to every copy of the repository.

| Step | Command | Result |
| --- | --- | --- |
| 1. Build | `make release-build` | `dist/`: the macOS (Apple Silicon) and Windows (x86-64 and Arm) packages, and `SHA256SUMS` |
| 2. Tag | `make release-tag` | the tag `v<version>` is pushed; the **Release** workflow creates the release on Rickub, with its notes |
| 3. Attach | by hand, on the release page | every file of `dist/` attached to the release |
| 4. After | `git fetch --tags` | the tag `v<version>` is in every copy of the repository |

The version is `info.version` in `build/config.yml`; the tag is `v` + that version.

## Before: set the version

1. In `build/config.yml`, set `info.version` (e.g. `"0.2.0"`).
2. `wails3 task common:update:build-assets`, then put `LSMinimumSystemVersion` back to `13.0.0` in `build/darwin/Info.plist` and `build/darwin/Info.dev.plist` (the command resets it to `12.0.0`).
3. Write what is new in `docs/release-notes/v<version>.md` (and `v<version>.fr.md`): the **Release** workflow puts the English one on the release page, under the files.
4. `make verify` ([checks before merging](docs/en/how-to/check-before-merging.md)), commit, merge into `main`, and `git checkout main && git pull`.

## 1. Build

```bash
make release-build
```

It builds, into `dist/`:

| Files | How |
| --- | --- |
| `Sidekicks-<v>-macos-arm64.dmg`, `.zip` | natively, for Apple Silicon only (Xcode command line tools) |
| `Sidekicks-<v>-windows-amd64-installer.exe`, `sidekicks_<v>_windows_amd64.zip` | cross-built (needs `brew install makensis`) |
| `Sidekicks-<v>-windows-arm64-installer.exe`, `sidekicks_<v>_windows_arm64.zip` | cross-built, for Windows on Arm |
| `SHA256SUMS` | over all the files above |

No Linux packages in the releases for now: `LINUX_ARCHES=amd64 make release-build` builds them too, in Docker. `SKIP="windows"` (or `macos`) leaves a system out; `WINDOWS_ARCHES=amd64` builds one Windows architecture only. The list of the files of a release is `scripts/package.sh release-names`.

**macOS signing**: with the Developer ID certificate, sign and notarize the macOS packages now, before tagging: [How to sign and notarize Sidekicks for macOS](docs/en/how-to/sign-and-notarize-on-macos.md), part B.

## 2. Tag

```bash
make release-tag
```

It refuses when the working tree has changes, when you are not on `main`, when `main` differs from `origin/main`, or when the tag exists; it warns when `dist/` misses a package. Then it creates the annotated tag `v<version>` and pushes it. The push starts `.github/workflows/release.yml`, which checks that the tag matches `build/config.yml` and creates the release with notes listing the files to expect.

## 3. Attach

Open the release on Rickub (**Releases → v<version>**), and attach every file of `dist/`, `SHA256SUMS` included.

## 4. After: fetch the tag

```bash
git fetch --tags
git tag --list 'v*'      # v<version> is listed
```

In every other copy of the repository (another machine, a sandbox, a clone made before the release), fetch the tags: the tag was pushed from the Mac, a plain `git pull` does not always bring it, and `git describe`, `git log v<previous>..v<version>` or the next release's notes need it.

## When something goes wrong

| Symptom | What to do |
| --- | --- |
| `makensis is missing` | `brew install makensis` — or `SKIP=windows`. |
| `the tag v… already exists` | That version was released already: raise `info.version`. |
| The workflow failed: "The tag is … but build/config.yml says …" | Delete the tag (`git push origin :refs/tags/v…` and `git tag -d v…`), fix `info.version`, start again. |
| The workflow ran but no release appeared | The job's log tells why (a `403` means the token could not write: `permissions: contents: write` must stay in `release.yml`). Create the release by hand on Rickub from the tag; the notes are in the job's log. |

Details: [How to publish a release](docs/en/how-to/publish-a-release.md) · [commands reference](docs/en/reference/commands.md).