Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .ai/contexts/build-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,15 @@ A failed or cancelled macOS tag build blocks automatic publication; no partial-p
`continue-on-error` path exists. Recovery and manifest consistency requirements
are in [releasing.md](../../docs/releasing.md).

`scripts/publish-release.sh` requires non-empty `GITHUB_REPOSITORY` and
`GITHUB_REF_NAME` before any gh call. The release lookup names the repository
in its API path; draft creation and every upload attempt pass
`--repo "${GITHUB_REPOSITORY}"`, so a clone's gh default cannot redirect writes.
The script tests execute Bash with a fake gh boundary and cover repository
selection, missing configuration, draft guards and upload retries. Manual
recovery downloads the tag run's artifacts, keeps the x64 copy of the colliding
pacman filename, then uses this script; see the release guide for commands.

Windows stays pinned to `windows-2022`: the Server 2025 image behind
`windows-latest` lacks the Visual Studio C++ toolchain needed by node-gyp for
node-pty. Linux stays split by architecture because electron-builder's native
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -141,4 +141,4 @@ jobs:
echo "**Full changelog**: ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/compare/${PREV_TAG}...${TAG}" >> release-notes.md
fi
# Stays a draft: edit only replaces the body.
gh release edit "$TAG" --notes-file release-notes.md
gh release edit "$TAG" --repo "${GITHUB_REPOSITORY}" --notes-file release-notes.md
50 changes: 43 additions & 7 deletions docs/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@
A release is a version tag on `main`. The version bump lands through a pull
request first, because `main` is protected.

Every `gh` command run by hand in this clone needs `--repo devsuitup/switchboard`:
gh's default here is the upstream repository, `doctly/switchboard`.

## Steps

1. **Bump the version and date the changelog** on a branch, and open the PR.
Expand Down Expand Up @@ -31,7 +34,7 @@ request first, because `main` is protected.
branch protection on `main` (`required_status_checks.contexts`). Both must
be updated together whenever the test matrix changes; workflow changes do
not change repository settings. The documented ruleset requires
no approving review, so `gh pr merge --auto --squash` can be armed once the
no approving review, so `gh pr merge --repo devsuitup/switchboard --auto --squash` can be armed once the
required checks run. CI-only PRs use the `no-changelog` label.

2. **Run the app before tagging.** The tag is what publishes, and nothing
Expand Down Expand Up @@ -68,11 +71,44 @@ request first, because `main` is protected.
To recover, re-run the failed macOS job in the tag's Actions run (or re-run
failed jobs) and let the dependent publish job run once every build succeeds.
Alternatively, create the release draft by hand using only artifacts from
that tag's successful builds and the tag's changelog section. If macOS
that tag's successful builds. In Bash, replace `<run>` with the tag's Actions
run ID and `<x.y.z>` with its version:

```bash
gh run download <run> --repo devsuitup/switchboard --dir .work-files/release-artifacts-v<x.y.z>
```

The download directory must not exist yet. Merge its `dist-*` artifact
directories into one fresh directory containing only the assets to upload.
Both Linux jobs produce `switchboard-doctly-<v>.pacman` with the same
filename: keep the copy from `dist-linux-x64` and discard the arm64 copy.
(CI merges the artifacts with `merge-multiple`, so which copy CI publishes
depends on download order: v0.0.104 shipped the aarch64 copy.) If macOS
artifacts are absent, omit `latest-mac.yml`. Never copy a previous release's
mac manifest: upload it only when its version, filenames, sizes and hashes
match the macOS files actually attached to this release. Check the draft's
assets before publishing it as described below.
match the macOS files actually attached to this release.

Create or complete the draft from the merged directory (`<dir>`):

```bash
GITHUB_REPOSITORY=devsuitup/switchboard GITHUB_REF_NAME=v<x.y.z> DIST_DIR=<dir> bash scripts/publish-release.sh
```

Both GitHub variables must be set and non-empty; the script refuses before
calling gh otherwise. It reads and writes the explicitly named repository.
From a checkout containing the tag's `CHANGELOG.md`, extract and attach its
notes, then inspect the draft's asset names and sizes:

```bash
node scripts/changelog-section.js v<x.y.z> > .work-files/release-notes.md
PREV_TAG="$(git describe --tags --abbrev=0 v<x.y.z>^)"
printf '\n**Full changelog**: https://github.com/devsuitup/switchboard/compare/%s...v<x.y.z>\n' "$PREV_TAG" >> .work-files/release-notes.md
gh release edit v<x.y.z> --repo devsuitup/switchboard --notes-file .work-files/release-notes.md
gh release view v<x.y.z> --repo devsuitup/switchboard --json assets --jq '.assets[] | {name, size}'
```

Check those assets against the merged directory and verify the update
manifests before publishing the draft as described below.

After all builds succeed, the publish job:
- creates a **draft** release named after the version;
Expand All @@ -85,12 +121,12 @@ request first, because `main` is protected.
changelog** link comparing the previous tag with this one. It fails
rather than publish an empty body when the section is missing or empty.
The fix is then in `CHANGELOG.md`, through a PR; `gh release edit
--notes-file` can fill in the draft by hand meanwhile.
--repo devsuitup/switchboard --notes-file` can fill in the draft by hand meanwhile.

Re-running CI while the release is a draft is fine: it completes or replaces
the draft's assets. CI refuses to publish if it cannot read the releases,
and never writes to a published release. Once published, add or replace an
asset by hand with `gh release upload --clobber` (see below), or tag a new
asset by hand with `gh release upload --repo devsuitup/switchboard --clobber` (see below), or tag a new
version. Delete the draft or move the tag only while the release is still a
draft. The workflow token has `contents: read`; only the publish job has
`contents: write`, and no checkout persists credentials.
Expand Down Expand Up @@ -151,7 +187,7 @@ can still receive a withdrawn pre-release.
- **Tag the merged commit, never the local bump commit.** A squash merge makes
a new commit; a tag on the pre-merge commit is not an ancestor of `main`, so
`git describe --tags` and the release-notes range skip it. If a build already
started from such a tag, cancel it (`gh run cancel`), delete the tag locally
started from such a tag, cancel it (`gh run cancel --repo devsuitup/switchboard`), delete the tag locally
and on `origin`, and tag the merged commit.
- **Unsigned macOS builds need `"mac": {"identity": null}` and
`"notarize": false` in `package.json`.** electron-builder reads a `CSC_LINK`
Expand Down
12 changes: 10 additions & 2 deletions scripts/publish-release.sh
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,14 @@
set -e

# see docs/releasing.md
if [ -z "${GITHUB_REPOSITORY:-}" ]; then
echo "::error::GITHUB_REPOSITORY must be set and non-empty"
exit 1
fi
if [ -z "${GITHUB_REF_NAME:-}" ]; then
echo "::error::GITHUB_REF_NAME must be set and non-empty"
exit 1
fi
if ! draft="$(gh api --paginate "repos/${GITHUB_REPOSITORY}/releases?per_page=100" --jq ".[] | select(.tag_name == \"${GITHUB_REF_NAME}\") | .draft")"; then
echo "::error::could not read the releases of ${GITHUB_REPOSITORY}; refusing to publish blind"
exit 1
Expand All @@ -11,7 +19,7 @@ case "$draft" in
gh release create "${GITHUB_REF_NAME}" \
--draft \
--title "${GITHUB_REF_NAME#v}" \
--notes ""
--notes "" --repo "${GITHUB_REPOSITORY}"
;;
true) echo "draft ${GITHUB_REF_NAME} already exists; proceeding to asset upload" ;;
*$'\n'*) echo "::error::more than one release carries ${GITHUB_REF_NAME}; refusing to pick one"; exit 1 ;;
Expand All @@ -22,7 +30,7 @@ for f in "${DIST_DIR:-dist}"/*; do
[ -f "$f" ] || continue
ok=0
for i in 1 2 3 4 5; do
if gh release upload "${GITHUB_REF_NAME}" "$f" --clobber; then ok=1; break; fi
if gh release upload "${GITHUB_REF_NAME}" "$f" --clobber --repo "${GITHUB_REPOSITORY}"; then ok=1; break; fi
echo "::warning::upload $(basename "$f") attempt $i failed; retrying in ${RETRY_DELAY:-10}s"
sleep "${RETRY_DELAY:-10}"
done
Expand Down
2 changes: 1 addition & 1 deletion test/changelog-section.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -45,5 +45,5 @@ test('the build workflow writes the release body from the tag\'s changelog secti
const workflow = fs.readFileSync(path.join(ROOT, '.github', 'workflows', 'build.yml'), 'utf8');
const step = workflow.slice(workflow.indexOf('- name: Fill in release notes'));
assert.match(step, /node scripts\/changelog-section\.js "\$TAG" > release-notes\.md/);
assert.match(step, /gh release edit "\$TAG" --notes-file release-notes\.md/);
assert.match(step, /gh release edit "\$TAG" --repo "\$\{GITHUB_REPOSITORY\}" --notes-file release-notes\.md/);
});
33 changes: 30 additions & 3 deletions test/publish-release.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ echo 'unexpected gh invocation' >&2
exit 2
`;

function runRelease(t, mode, failOnce = false, draftValue = 'false') {
function runRelease(t, mode, failOnce = false, draftValue = 'false', envOverrides = {}) {
const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'publish-release-'));
t.after(() => fs.rmSync(temp, { recursive: true, force: true }));
const bin = path.join(temp, 'bin');
Expand Down Expand Up @@ -75,6 +75,10 @@ function runRelease(t, mode, failOnce = false, draftValue = 'false') {
GH_STUB_FAIL_ONCE: failOnce ? '1' : '0',
GH_STUB_RETRY_FILE: shellPath(path.join(temp, 'retried')),
});
for (const [key, value] of Object.entries(envOverrides)) {
if (value === undefined) delete env[key];
else env[key] = value;
}
const result = spawnSync(bash, [shellPath(script)], {
cwd: temp, env, encoding: 'utf8', timeout: 10000,
});
Expand All @@ -94,7 +98,7 @@ function requireBash(t) {

function assertUploads(result, names) {
assert.deepEqual(result.calls.filter((args) => args[1] === 'upload'), names.map((name) => [
'release', 'upload', TAG, `${result.dist}/${name}`, '--clobber',
'release', 'upload', TAG, `${result.dist}/${name}`, '--clobber', '--repo', REPOSITORY,
]));
}

Expand All @@ -109,7 +113,7 @@ test('given a missing release, publishing creates a draft and uploads both asset
'api', '--paginate', `repos/${REPOSITORY}/releases?per_page=100`, '--jq',
`.[] | select(.tag_name == "${TAG}") | .draft`,
]);
assert.deepEqual(result.calls[1], ['release', 'create', TAG, '--draft', '--title', '0.1.0', '--notes', '']);
assert.deepEqual(result.calls[1], ['release', 'create', TAG, '--draft', '--title', '0.1.0', '--notes', '', '--repo', REPOSITORY]);
assertUploads(result, ['one.zip', 'two.exe']);
});

Expand Down Expand Up @@ -158,3 +162,26 @@ test('given a draft and one failed upload, publishing retries and exits 0', (t)
assert.match(result.stdout, /attempt 1 failed; retrying in 0s/);
assertUploads(result, ['one.zip', 'one.zip', 'two.exe']);
});

for (const variable of ['GITHUB_REPOSITORY', 'GITHUB_REF_NAME']) {
for (const value of [undefined, '']) {
test(`given ${variable} is ${value === undefined ? 'unset' : 'empty'}, publishing refuses before calling gh`, (t) => {
if (!requireBash(t)) return;
const result = runRelease(t, 'missing', false, 'false', { [variable]: value });
assert.equal(result.status, 1, `${variable} must be required`);
assert.match(result.stdout + result.stderr, new RegExp(`::error::.*${variable}`));
assert.deepEqual(result.calls, [], 'invalid configuration must not call gh');
});
}
}

test('given another repository, publishing reads and writes that repository', (t) => {
if (!requireBash(t)) return;
const repository = 'another-owner/release-target';
const result = runRelease(t, 'missing', false, 'false', { GITHUB_REPOSITORY: repository });
assert.equal(result.status, 0, result.stderr);
assert.equal(result.calls[0][2], `repos/${repository}/releases?per_page=100`);
for (const call of result.calls.slice(1)) {
assert.deepEqual(call.slice(-2), ['--repo', repository]);
}
});
Loading