laantungir/amethyst
1
0
Fork 0
mirror of https://github.com/vitorpamplona/amethyst.git synced 2026-10-05 19:28:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: correct three release-doc claims the v1.14.0 release disproved

Browse Source 
All three were found by following the docs during the v1.14.0 release and
hitting reality instead.

1. The Homebrew cask bootstrap command cannot work. BUILDING.md told the
   maintainer to run `brew bump-cask-pr amethyst-nostr` for the *one-time
   initial PR*, but that subcommand updates an existing cask. Against a name
   not in the tap it fails outright:

     Error: Cask 'amethyst-nostr' is unavailable: No Cask with this name exists.

   Verified by dry-run. A first submission is a new-cask PR — `brew create
   --cask`, `brew audit --new --cask`, then a hand-opened PR — so the section
   now documents that flow, notes the notarized+stapled precondition Homebrew
   enforces, and says where `bump-cask-pr` *does* apply (the later bumps).
   This is plausibly why the bootstrap never happened.

2. RELEASE_OPS claimed the release holds 31 assets. It holds 47. The windows-
   arm64 and linux-arm64 legs added this cycle took desktop 8 -> 14, amy 5 ->
   10 and geode 5 -> 10. BUILDING.md had already been updated; RELEASE_OPS had
   not, in two places (the § 2 breakdown and the § 6 checklist). A maintainer
   following it would read a correct release as broken. The breakdown now
   points at BUILDING.md, which carries the per-leg detail and the reasons for
   the two gaps, rather than restating it and drifting again. Also drops the
   geode Docker image from the count — it goes to the registry, not the
   release.

3. RELEASE_OPS § 3 said to verify "Intel + ARM DMGs are both present" while
   § 2 and § 6 said macOS is arm64-only. Only the arm64 DMG exists, so § 3 was
   the wrong one.

Also replaces the "neither has ever been submitted upstream" line with a
per-channel table: Winget is now submitted (microsoft/winget-pkgs#422752,
pending CLA), both Homebrew packages are not. Since that is a snapshot that
will age, it carries the one-call check that answers it live.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gs2gi3sZfQ7SHrVm2njLMw
This commit is contained in:
Vitor Pamplona
2026-08-22 20:31:53 -04:00
co-authored by Claude Opus 5
parent 10149d7150
commit 1aeb194368
2 changed files with 54 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
BUILDING.md
+23 -5
View File
@@ -533,7 +533,7 @@ reads an optional per-release changelog from
## Bootstrap runbook (one-time)
> **Status as of v1.14.0: neither Homebrew nor Winget has been bootstrapped.**
> **Status as of v1.14.0:** Winget has been submitted — [microsoft/winget-pkgs#422752](https://github.com/microsoft/winget-pkgs/pull/422752), pending CLA + review. Neither Homebrew package (`amethyst-nostr` cask, `amy` formula) has been submitted yet.
> `https://formulae.brew.sh/api/cask/amethyst-nostr.json` and
> `microsoft/winget-pkgs/manifests/v/VitorPamplona/Amethyst` both 404, so
> **Amethyst does not currently ship through either channel.** The bump
@@ -618,15 +618,33 @@ that is needed.
### Homebrew cask (one-time initial PR)
> `brew bump-cask-pr` **cannot** do this step. It *updates* an existing cask —
> against a name that isn't in the tap yet it fails outright:
> `Error: Cask 'amethyst-nostr' is unavailable: No Cask with this name exists.`
> The first submission is a **new-cask** PR, which is a different flow:
```bash
brew bump-cask-pr amethyst-nostr \
--version 1.12.1 \
--url "https://github.com/vitorpamplona/amethyst/releases/download/v1.12.1/amethyst-desktop-1.12.1-macos-arm64.dmg"
# 1. Scaffold from the published DMG (macOS arm64 — there is no Intel DMG)
brew create --cask \
https://github.com/vitorpamplona/amethyst/releases/download/v1.14.0/amethyst-desktop-1.14.0-macos-arm64.dmg \
--set-name amethyst-nostr
# 2. Fill in the cask body, then audit as a NEW cask (stricter than a bump)
brew audit --new --cask amethyst-nostr
brew install --cask amethyst-nostr # verify it actually installs
brew uninstall --cask amethyst-nostr
# 3. Open the PR against Homebrew/homebrew-cask by hand
```
The DMG **must be notarized and stapled** or Homebrew will reject it; verify
with `spctl -a -t open --context context:primary-signature -v <dmg>` before
submitting.
The cask filename is `amethyst-nostr` (not `amethyst` — that's taken by a
tiling window manager). After the first PR is merged, `bump-homebrew.yml`
auto-submits new version bumps on each stable release.
auto-submits new version bumps on each stable release — *that* is where
`brew bump-cask-pr` applies.
> **The desktop app is already on mainline Homebrew.** `homebrew/cask` *is* the
> mainline cask repo — GUI apps live in homebrew-**cask**, CLIs in
RELEASE_OPS.md
+31 -13
View File
@@ -101,15 +101,20 @@ git -c credential.helper= -c credential.helper='!gh auth git-credential' push up
```
When the `Create Release Assets` workflow finishes (~25–30 min) the GH Release
holds **31 assets**, per the asset-name contract:
holds **47 assets**, per the asset-name contract:
- **Android (13):** 5 Google Play APKs + 5 F-Droid APKs + 2 AABs + the F-Droid
`.apks` set for Accrescent
(`amethyst-googleplay-*-v…apk` / `.aab`, `amethyst-fdroid-*-v…apk` / `.aab` / `.apks`)
- **Desktop (8):** DMG (macOS **arm64 only** — there is no Intel DMG),
MSI + zip, DEB, RPM, AppImage, flatpak, tar.gz
- **CLI (5):** the `amy` artifacts
- **Relay (5):** the `geode` artifacts, plus the geode Docker image
- **Desktop (14):** macOS DMG (**arm64 only** — there is no Intel DMG), Windows
MSI (x64 only — **no arm64 MSI**) + portable zip (x64, arm64), and Linux
DEB/RPM/AppImage/flatpak/tar.gz in both x64 and arm64. BUILDING.md § Release
runbook has the per-leg breakdown and why the two gaps exist.
- **CLI (10):** the `amy` artifacts — the no-JRE `jvm.tar.gz`, macOS arm64,
Windows x64 + arm64, and Linux DEB/RPM/tar.gz in both x64 and arm64
- **Relay (10):** the `geode` artifacts, same matrix as `amy`. The geode Docker
image is **not** a release asset — it goes to the registry, so don't count it
here.
- **Maven Central:** `com.vitorpamplona.quartz:quartz:<version>` published.
`repo1.maven.org` lags the publish by tens of minutes — a 404 right after the
run is normal. Confirm the step's log says "Deployment is being published to
@@ -121,8 +126,9 @@ holds **31 assets**, per the asset-name contract:
## 3. Per-channel shipping
### GitHub Releases — automatic
Nothing to do beyond pushing the tag. Verify the asset count and that Intel +
ARM DMGs are both present (BUILDING.md § Verify).
Nothing to do beyond pushing the tag. Verify the asset count (BUILDING.md
§ Verify). macOS is **arm64-only** — there is no Intel DMG, so a single
`amethyst-desktop-<version>-macos-arm64.dmg` is the expected, correct result.
### Google Play — manual upload
1. Download `amethyst-googleplay-<version>.aab` from the GH Release.
@@ -177,7 +183,7 @@ when unset. To fan the release event out to more relays for discoverability,
set `RELAY_URLS` for the run:
```bash
RELAY_URLS="wss://relay.zapstore.dev,wss://relay.damus.io,wss://nos.lol,wss://vitor.nostr1.com" \
RELAY_URLS="wss://relay.zapstore.dev,wss://nos.lol,wss://nostr.mom,wss://vitor.nostr1.com" \
SIGN_WITH=<amethyst-nsec> zsp publish
```
@@ -188,10 +194,22 @@ itself reads from.
`bump-homebrew.yml` and `bump-winget.yml` are wired to open PRs against
`Homebrew/homebrew-cask` (cask `amethyst-nostr`) and `microsoft/winget-pkgs`
(`VitorPamplona.Amethyst`) — but **neither package has ever been submitted
upstream**, so both workflows detect that and skip with a `::warning::`. As of
**v1.14.0** these two channels deliver nothing; macOS and Windows users get the
desktop app from GitHub Releases only.
(`VitorPamplona.Amethyst`). Both can only *update* a package that already
exists upstream, so until the one-time bootstrap lands they detect the absence
and skip with a `::warning::`.
Bootstrap status:
| Channel | Upstream package | State |
|---|---|---|
| **Winget** | `microsoft/winget-pkgs` → `VitorPamplona.Amethyst` | **Submitted at v1.14.0** — [PR #422752](https://github.com/microsoft/winget-pkgs/pull/422752), pending CLA + review |
| **Homebrew cask** | `Homebrew/homebrew-cask` → `amethyst-nostr` | Not submitted |
| **Homebrew formula** | `Homebrew/homebrew-core` → `amy` | Not submitted |
Until each lands, that channel delivers nothing and macOS/Windows users get the
desktop app from GitHub Releases only. Re-check before assuming — the state
above is a snapshot, and `gh api repos/microsoft/winget-pkgs/contents/manifests/v/VitorPamplona`
(404 = still absent) answers it in one call.
Two separate faults kept this invisible until v1.13.1, both now fixed:
@@ -283,7 +301,7 @@ Owner assignments and rotation reminders live with the team (issue tracker).
## 6. Post-release verification
- [ ] GH Release: 31 assets, sizes sane, and the asset-name set matches the
- [ ] GH Release: 47 assets, sizes sane, and the asset-name set matches the
previous release (see the `diff` one-liner in BUILDING.md § Release
runbook). macOS is arm64-only — do **not** look for an Intel DMG.
- [ ] Maven Central: `quartz:<version>` resolves (allow tens of minutes of