Alas releases ship a signed + notarized macOS DMG, an Alas-X.Y.Z-arm64.app.zip,
and a Homebrew cask bump in mrmans0n/homebrew-tap. All of that runs from
.github/workflows/release.yml on tag push.
This doc covers the human side: cutting CHANGELOG.md and bumping the version.
# 1. Draft entries from commits since the last v* tag.
./scripts/draft-release-notes.sh --write
# 2. Open CHANGELOG.md and polish the [Unreleased] section.
$EDITOR CHANGELOG.md
# 3. Promote the curated notes into the new version section.
./scripts/draft-release-notes.sh --target 0.1.2 --write
# 4. Pick the what's new highlights (see "What's new entries" below).
# Skip this step to ship without a card.
$EDITOR Alas/Resources/WhatsNew/0.1.2.json
# Optional media: Alas/Resources/WhatsNew/media/0.1.2-<slug>.gif (under ~2 MB)
# 5. Preview the TestFlight "What to Test" text. If the release has no
# mobile-facing What's New body or changelog item, add the explicit override.
ruby scripts/testflight-notes.rb --version 0.1.2 \
--release-url https://github.com/mrmans0n/alas/releases/tag/v0.1.2
# $EDITOR Mobile/TestFlight/WhatToTest/0.1.2.md
# 6. Bump the version in project.yml, regenerate Xcode project.
$EDITOR project.yml # bump CFBundleShortVersionString + CFBundleVersion
xcodegen
# 7. Commit and tag.
git add CHANGELOG.md project.yml Alas.xcodeproj Alas/Resources/WhatsNew
# If step 5 added an override:
# git add Mobile/TestFlight/WhatToTest/0.1.2.md
git commit -m "Bump version to 0.1.2"
git tag v0.1.2
git push origin main v0.1.2The Release Artifacts workflow will pick up v0.1.2, build/sign/notarize
the app, extract the [0.1.2] section from CHANGELOG.md, and publish a
GitHub Release with that body. If CHANGELOG.md has no matching section the
workflow hard-fails — fix and re-tag.
After updating, Alas shows a one-time "What's new" card for the newest entry between the last-seen version and the running one. Stable builds only. Entries are curated by hand at release time; a release with no entry shows no card.
In step 4, read the new version's ✨ Features section and pick one headline
and up to two "also" items, or none. Rewrite them as short marketing copy, not
the changelog sentence. "None" means no file.
Entries live in Alas/Resources/WhatsNew/<version>.json, bundled into the app:
{
"version": "0.22.0",
"headline": {
"title": "Plugins",
"body": "Extend Alas with your own panes and commands.",
"media": "media/0.22.0-plugins.gif",
"action": "openPluginSettings",
"actionLabel": "Try plugins"
},
"also": [
{ "title": "@ symbols in composer" },
{ "title": "Faster worktrees" }
]
}versionmust equal the filename stem (0.22.0.json).headline.titleandheadline.bodyare required; the body is one sentence.mediais optional, relative to theWhatsNewfolder, and must stay inside it. Convention:media/<version>-<slug>.gif, under ~2 MB.actionis optional and must be one of the identifiers below.actionLabelis the button text and defaults to "Try it".alsois optional, at most two items.
Valid action identifiers (defined by WhatsNewAction in
Packages/AlasCore/Sources/AlasCore/Updates/WhatsNew.swift):
| Action | Effect |
|---|---|
openPluginSettings |
Opens Settings → Plugins |
openComputerUseSettings |
Opens Settings → Computer Use |
Adding an action is an app change (a new WhatsNewAction case plus its
handling in RootView), shipped with the feature it showcases.
To preview an entry locally, run a build whose version is at or above the entry and use Help → What's New…, which reopens the newest entry at or below the running version.
Entries are validated by the committedEntriesAreValid test in WhatsNewTests:
swift test --package-path Packages/AlasCore --filter WhatsNewTestsThe release workflow runs it in the whats-new-check job, and publish
needs that job, so an invalid entry (bad JSON, version/filename mismatch,
missing media, unknown action, more than two also items) blocks the release.
Every iOS beta upload passes app-specific English text to TestFlight followed by a blank line and the canonical GitHub Release URL. The text is generated from immutable content in the checked-out release ref, in this order:
Mobile/TestFlight/WhatToTest/<version>.md, when the release needs curated mobile copy that cannot be derived safely. Store only the app-specific body; the generator owns and appends the release link;- the versioned What's New headline body, when it mentions iPhone, iPad, iOS, or mobile behavior;
- up to three mobile-facing bullets from that version's
CHANGELOG.mdsection.
For a vX.Y.Z release, the generator fails instead of reusing generic or stale
copy when none of those sources exists. Add the versioned override and rerun:
ruby scripts/testflight-notes.rb --version X.Y.Z \
--release-url https://github.com/mrmans0n/alas/releases/tag/vX.Y.ZManual branch builds use a concise Alas beta checklist and link to the branch; nightlies use the same checklist and link to the built commit. Generated text must stay within Fastlane's effective 4,000-byte TestFlight limit. The iOS workflow prints the exact generated body before passing the same to Fastlane, so release verification can compare the submitted text with the tagged input.
--since <ref>— override the base ref (default: latest reachablev*tag).--target <version>— render under a versioned heading instead of[Unreleased].--write— splice intoCHANGELOG.mdrather than printing.--include-internal— includeci/test/build/stylecommits under🏗️ Internal(default skips them).
| Prefix | Where it lands |
|---|---|
feat: |
✨ Features |
fix: |
🐛 Fixes |
refactor:, perf:, chore: |
🏗️ Internal |
docs: |
📚 Docs |
ci:, test:, build:, style: |
dropped unless --include-internal |
PR titles follow the same convention since the repo uses squash merges.