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
10 changes: 10 additions & 0 deletions docs/QUALITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Quality requirements

Each entry names a scenario, the required response, how it is measured, and the check that proves it.

## Release

| ID | Attribute | Scenario | Response | Measure | Check |
|---|---|---|---|---|---|
| Q-REL-1 | security | a full `scripts/release.sh` run | no ASC API key or Sparkle EdDSA private key value appears in stdout, stderr, `checks.md`, or any file left under `--out` or the temp dir after exit | 0 hits | the "No key material left" row of every `checks.md`; `secrets-cleanup-on-failure`, `leak-scan-detects` and `refuse-xtrace` in `scripts/test-release.sh` |
| Q-REL-2 | integrity | a release run with N published prior appcast items | the new appcast holds N+1 items, each prior item byte-identical, each enclosure signature valid against the shipped `SUPublicEDKey` | N of N identical, N+1 of N+1 VALID | the "Prior items verbatim" and "Enclosure" rows of `checks.md`; the `appcast-*` and `cut-cmp-*` cases in `scripts/test-release.sh` |
43 changes: 36 additions & 7 deletions docs/RUNBOOK.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,15 +106,35 @@ the real `/Applications`). Never judge arrow or hiding behaviour on a copy outsi
(every occurrence: the App Store target's four configurations plus the
Direct target's four; `grep -c MARKETING_VERSION` must match the count you
edited).
3. Archive the GitHub build with the **Hidden Bar** scheme
(`Release-Direct`; builds the **Hidden Bar Direct** target), then notarize (Developer ID), staple, zip, and publish a
GitHub release with notes listing closed issues. The **Hidden Bar App Store**
scheme archives `Release`, the sandboxed App Store build, which cannot hide
on macOS 27. v1.11 shipped that build to GitHub by mistake. Before zipping,
confirm the app is unsandboxed:
3. Build the GitHub release artifacts with one command, on the Mac mini, from a
clean tree at the release commit:

```sh
codesign -d --entitlements - 'Hidden Bar.app' | grep app-sandbox # must print nothing
scripts/release.sh --notes notes.html # <ul>...</ul> for the appcast item
```

It runs the tests, archives the **Hidden Bar** scheme (`Release-Direct`;
builds the **Hidden Bar Direct** target), checks the app, notarizes,
staples, zips, EdDSA-signs, builds `appcast.xml`, smoke-tests the zip with
a host restore, and writes `build/release-<version>/checks.md` with one row
per check. It never tags, uploads or publishes; `checks.md` ends with the
publish commands as text. `scripts/release.sh --check-app <app>` runs the
app checks alone on any bundle; `bash scripts/test-release.sh` tests the
script offline. The steps below are what the script does, for a manual
run or when the script is broken on release day.

The **Hidden Bar App Store** scheme archives `Release`, the sandboxed App
Store build, which cannot hide on macOS 27. v1.11 shipped that build to
GitHub by mistake. Before zipping, confirm the app is signed Developer ID
first, then that it is unsandboxed. The order matters: an ad-hoc or
unsigned build has no entitlements, so the sandbox grep alone prints
nothing and passes on the wrong build.

```sh
codesign -dvv 'Hidden Bar.app' 2>&1 | grep -E '^Authority=Developer ID Application: .*\(W777S7V8TN\)$|^Timestamp=|flags=.*runtime'
# must print 3 lines: the Developer ID authority, a Timestamp, and runtime flags
codesign -d --entitlements - --xml 'Hidden Bar.app' # must print a plist ...
codesign -d --entitlements - --xml 'Hidden Bar.app' | grep -c app-sandbox # ... and this must print 0
```

The target signs automatically for development, so a plain archive fails
Expand Down Expand Up @@ -151,6 +171,15 @@ lives in 1Password (`dfoundation-prod`, item "Hidden Bar Sparkle EdDSA private
key"); only the public key (`SUPublicEDKey`) is in the repo. Losing the key
means no installed copy can ever verify another update, so never regenerate it.

`scripts/release.sh` does steps 1 to 3 below and writes the zips and
`appcast.xml` under `build/release-<version>/`: it signs with `sign_update`
from the pinned Sparkle tarball (sha256 checked every run), verifies every
enclosure against `SUPublicEDKey` (pinned in the script), and builds the
appcast by prepending the new item to the latest published `appcast.xml`, so
every prior item stays byte-identical (it does not use `generate_appcast`,
which rewrites prior items). Steps 4 and 5, the upload and publish, stay
manual; `checks.md` prints them. The manual commands, for reference:

Sparkle's `sign_update` and `generate_appcast` come from the Sparkle release
tarball matching the pinned package version (2.10.1, `Sparkle-<ver>.tar.xz`
under `bin/`). Run from a folder that holds only the zip(s) to publish:
Expand Down
18 changes: 18 additions & 0 deletions scripts/fixtures/release/item-1.12.0.expected
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<item>
<title>Version 1.12.0</title>
<pubDate>Sun, 15 Nov 2026 16:33:08 GMT</pubDate>
<sparkle:version>19</sparkle:version>
<sparkle:shortVersionString>1.12.0</sparkle:shortVersionString>
<sparkle:minimumSystemVersion>13.0</sparkle:minimumSystemVersion>
<sparkle:fullReleaseNotesLink>https://github.com/dwarvesf/hidden/releases/tag/v1.12.0</sparkle:fullReleaseNotesLink>
<description><![CDATA[
<ul>
<li>A redesigned Settings window.</li>
<li>Hiding works again while an app keeps the microphone open (Wispr Flow, Krisp, Discord...).</li>
<li>Switching from the App Store version offers to import your settings.</li>
<li>macOS 27: pinned sections (beta) keep icons where you put them after apps restart.</li>
<li>Fixes for macOS 26 and earlier.</li>
</ul>
]]></description>
<enclosure url="https://github.com/dwarvesf/hidden/releases/download/v1.12.0/Hidden-Bar-v1.12.0-macos.zip" sparkle:edSignature="qAsECvbmtEMdTEWB3C8crQ3PZy4JhXBRbEfZjgZ3rYmzYP+WKIJJXoH6PxsYag7/J+yKZH79EuU5mlNfe6zTBQ==" length="2174551" type="application/octet-stream"/>
</item>
7 changes: 7 additions & 0 deletions scripts/fixtures/release/notes-1.12.0.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
<ul>
<li>A redesigned Settings window.</li>
<li>Hiding works again while an app keeps the microphone open (Wispr Flow, Krisp, Discord...).</li>
<li>Switching from the App Store version offers to import your settings.</li>
<li>macOS 27: pinned sections (beta) keep icons where you put them after apps restart.</li>
<li>Fixes for macOS 26 and earlier.</li>
</ul>
1 change: 1 addition & 0 deletions scripts/fixtures/release/payload.bin
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Hidden Bar release-script fixture payload
1 change: 1 addition & 0 deletions scripts/fixtures/release/payload.sig.b64
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
qAsECvbmtEMdTEWB3C8crQ3PZy4JhXBRbEfZjgZ3rYmzYP+WKIJJXoH6PxsYag7/J+yKZH79EuU5mlNfe6zTBQ==
26 changes: 26 additions & 0 deletions scripts/fixtures/release/prior-1.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" xmlns:dc="http://purl.org/dc/elements/1.1/">
<channel>
<title>Hidden Bar</title>
<link>https://github.com/dwarvesf/hidden</link>
<description>Hidden Bar updates</description>
<language>en</language>
<item>
<title>Version 1.11.2</title>
<pubDate>Sun, 15 Nov 2026 06:50:21 GMT</pubDate>
<sparkle:version>17</sparkle:version>
<sparkle:shortVersionString>1.11.2</sparkle:shortVersionString>
<sparkle:minimumSystemVersion>13.0</sparkle:minimumSystemVersion>
<sparkle:fullReleaseNotesLink>https://github.com/dwarvesf/hidden/releases/tag/v1.11.2</sparkle:fullReleaseNotesLink>
<description><![CDATA[
<ul>
<li>macOS 27: clicking the clock opens Notification Center again.</li>
<li>Icons you keep right of the arrow stay visible.</li>
<li>Microphone and camera indicators are no longer hidden.</li>
<li>Multi-display fixes, auto-update, and Turkish, Ukrainian and Italian translations.</li>
</ul>
]]></description>
<enclosure url="https://github.com/dwarvesf/hidden/releases/download/v1.11.2/Hidden-Bar-v1.11.2-macos.zip" length="2026759" type="application/octet-stream" sparkle:edSignature="qAsECvbmtEMdTEWB3C8crQ3PZy4JhXBRbEfZjgZ3rYmzYP+WKIJJXoH6PxsYag7/J+yKZH79EuU5mlNfe6zTBQ=="/>
</item>
</channel>
</rss>
44 changes: 44 additions & 0 deletions scripts/fixtures/release/prior-2.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" xmlns:dc="http://purl.org/dc/elements/1.1/">
<channel>
<title>Hidden Bar</title>
<link>https://github.com/dwarvesf/hidden</link>
<description>Hidden Bar updates</description>
<language>en</language>
<item>
<title>Version 1.12.0</title>
<pubDate>Sun, 15 Nov 2026 16:33:08 GMT</pubDate>
<sparkle:version>19</sparkle:version>
<sparkle:shortVersionString>1.12.0</sparkle:shortVersionString>
<sparkle:minimumSystemVersion>13.0</sparkle:minimumSystemVersion>
<sparkle:fullReleaseNotesLink>https://github.com/dwarvesf/hidden/releases/tag/v1.12.0</sparkle:fullReleaseNotesLink>
<description><![CDATA[
<ul>
<li>A redesigned Settings window.</li>
<li>Hiding works again while an app keeps the microphone open (Wispr Flow, Krisp, Discord...).</li>
<li>Switching from the App Store version offers to import your settings.</li>
<li>macOS 27: pinned sections (beta) keep icons where you put them after apps restart.</li>
<li>Fixes for macOS 26 and earlier.</li>
</ul>
]]></description>
<enclosure url="https://github.com/dwarvesf/hidden/releases/download/v1.12.0/Hidden-Bar-v1.12.0-macos.zip" sparkle:edSignature="qAsECvbmtEMdTEWB3C8crQ3PZy4JhXBRbEfZjgZ3rYmzYP+WKIJJXoH6PxsYag7/J+yKZH79EuU5mlNfe6zTBQ==" length="2174551" type="application/octet-stream"/>
</item>
<item>
<title>Version 1.11.2</title>
<pubDate>Sun, 15 Nov 2026 06:50:21 GMT</pubDate>
<sparkle:version>17</sparkle:version>
<sparkle:shortVersionString>1.11.2</sparkle:shortVersionString>
<sparkle:minimumSystemVersion>13.0</sparkle:minimumSystemVersion>
<sparkle:fullReleaseNotesLink>https://github.com/dwarvesf/hidden/releases/tag/v1.11.2</sparkle:fullReleaseNotesLink>
<description><![CDATA[
<ul>
<li>macOS 27: clicking the clock opens Notification Center again.</li>
<li>Icons you keep right of the arrow stay visible.</li>
<li>Microphone and camera indicators are no longer hidden.</li>
<li>Multi-display fixes, auto-update, and Turkish, Ukrainian and Italian translations.</li>
</ul>
]]></description>
<enclosure url="https://github.com/dwarvesf/hidden/releases/download/v1.11.2/Hidden-Bar-v1.11.2-macos.zip" length="2026759" type="application/octet-stream" sparkle:edSignature="qAsECvbmtEMdTEWB3C8crQ3PZy4JhXBRbEfZjgZ3rYmzYP+WKIJJXoH6PxsYag7/J+yKZH79EuU5mlNfe6zTBQ=="/>
</item>
</channel>
</rss>
1 change: 1 addition & 0 deletions scripts/fixtures/release/pub.b64
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
W7SukNcz0ZbDXDm/XnJgtc8RTz7s9OrSWaST/rz6EmU=
1 change: 1 addition & 0 deletions scripts/fixtures/release/wrongkey.pub.b64
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
4wa+sFG3gaWUVoA5U9Tru+uTFe/x+r4eSx9I7cI0Md4=
Loading