Release overhaul

[rgoldberg]

Release Workflow

The automated release workflow shouldn't be kicked off when a release has been published (on: release: types: published), because the release will have then already been made available to the public.

If anything fails or is suboptimal (like poorly worded generated release notes) in the workflow, we'd need to either delete, modify, or supersede the botched release, all of which are suboptimal.

It's best to split the release process into 3 stages:

Stage 1: Generate Draft

• When a tag matching a version string regex (v\d+\.\d+\.\d+(?:-(?:alpha|beta|rc)\.\d+)?) is pushed to the main branch of the mas-cli/mas repo, run a workflow that will:
  • Validate all inputs.
    • Ensure that the the tag is annotated & signed, and that its message corresponds to the tag name.
    • Otherwise (e.g., the tag is lightweight, unsigned, or its message is improperly formatted), the tag will be rejected.
  • Stop progressing if any step fails.
    • Revert prior steps if any step fails.
  • Checkout the version tag
  • Bootstrap
  • Build
  • Package the *.pkg(s)
  • Create a GitHub Release draft.
    • Autogenerate release notes.
    • Label the draft as a prerelease if the version tag contains a -.
      • For prereleases, skip steps that should be skipped for prereleases (like bumping homebrew-core formula).
  • Upload the *.pkg(s) to the draft
  • Create a mas-cli/tap/mas formula bump PR
• In an emergency, a release can be made manually via the GitHub web or cli interface

Stage 2: Manual Draft Inspection / Modification

After inspecting everything created in stage 1, the releaser may then either:

• Publish the draft as a release as is
• Modify the draft, then publish the draft as a release
• Delete the draft

Stage 3: Publish Release / Delete Draft

If the releaser deletes the GitHub Release draft in stage 2, then an on: release: types: deleted workflow will close the related external PRs & remove as much stuff as possible.

If the releaser publishes the draft, then an on: release: types: published workflow will:

• Bump the homebrew-core mas formula.
• Approve / apply the pr-pull label to the mas-cli/tap/mas formula bump PR, which will generate & publish bottles stored in a new GitHub Release for the new version in mas-cli/homebrew-tap for:
  • Intel for macOS 10.13 & newer.
  • Apple Silicon for macOS 11 & newer.

The custom tap bottle generation & publishing process will be as follows (I hope it will work; if it doesn't, I'll devise a workaround & let you know):

• When the custom tap formula PR is pushed to mas-cli/tap, the tests.yml workflow will:
  • Build one bottle each for arm64 & x86_64 on macos-15
  • Rename each bottle from *sequoia* to the macOS version name for the oldest supported macOS version for each platform (i.e. *big_sur* for arm64 & *high_sierra* for x86_64)
    • Download the mas 1.8.6 el_capitan bottle for x86_64 from the 1.8.6 release
    • Upload all 3 bottles as artifacts to the GitHub PR
• When the PR is labelled with pr-pull, the publish.yml workflow will:
  • Publish the 3 bottles to a new GitHub Release for the new mas version in the custom tap repo.

Legacy Version Patch Branches

If we ever release patches for legacy mas versions, they should be done in a legacy version patch branch.

Given that we aren't patching legacy versions right now, the first revamp of the new release system doesn't need to support it, but we might want to think through the workflow to support it in the future.

See #655 for details about legacy version patch branches & other git-related proposals.

Current Work

• Implement the 3 stages outlined above.
• If possible, replace lightweight version tags with backdated signed annotated tags.
• GitHub Release artifacts:
  • Include version (& platform? & macOS version?) in mas.pkg filename.
    • Future versions
    • Existing versions
  • Universal vs. platform-specific installers.
• mas-cli/tap/mas:
  • Provide 1.8.6 bottle for macOS 10.11 & 10.12, because 1.8.7+ requires macOS 10.13+.
  • Manually generate bottles for macOS 10.13 & 10.14, because brew bump-formula-pr probably won't do that.
  • Remove bottles from custom tap that are available from homebrew-core?
  • Instead of using a single universal executable for all supported macOS versions, generate bottles for each supported platform & version of macOS?
  • Bottles in mas-cli/homebrew-tap instead of in mas-cli/mas
  • Tap version tags.
    • Future versions
    • Existing versions
• 📝 Document release process #357

Possible Future Tasks

• Rename build-test.yml as build-test-lint.yml.
• Cleanup actions/checkout@v4 output:
  • git config --global init.defaultBranch main
  • git config --global advice.detachedHead false
• Dangerfile.swift appears to be used only for PRs made directly on mas-cli/mas, not for those via forks:
  • Setup for fork PRs.
  • Or delete it.
• release.yml:
  • Limit env variables to specific steps?
• Move .github/*.yml into .github/workflows?
• GitHub/git protections #655
• Use YAML & JSON schemas for validation #657
• Remove Distribution.plist; replace with a heredoc / process substitution in script/package #677

Completed

• Remove extraneous files from mas-cli/mas repo:
  • Makefile
  • .github/event.json
  • Many shell scripts
  • Homebrew formulae: store each only in its respective tap repo, e.g., homebrew/homebrew-core or mas-cli/tap
    • Bump homebrew-core & mas-cli/tap/mas formulae in taps instead of locally generating / modifying them.
      • Do not create a manual pull request for the custom tap.
  • Generate files only when absolutely necessary, but git ignore them, e.g., Sources/mas/Package.swift
• Do not commit or branch in mas-cli/mas on release.
• Store values in as few places as possible, e.g.:
  • Store version in mas-cli/mas repo only in version tag, not in any files or in any branch names.
• Reuse existing functionality (like brew bump-formula-pr) instead of reinventing the wheel.
• Standardize:
  • Ensure the same tools are used everywhere, e.g.:
    • ensure /bin/bash is used everywhere instead of some places using bash from the $PATH.
  • Remove dependencies whose functionality can be performed by other things, e.g.:
    • sd: script that used it was deleted, but if script had been kept, should use shell scripting instead
    • mise: use brew bundle instead
• Scope code, e.g.,:
  • Formulae should be bumped only during a release, so do not perform bumps in scripts called by release workflow; instead, embed bumps in the workflow itself, otherwise people might incorrectly run bump scripts outside of the workflow.
    • If, under extraordinary circumstances, someone must bump the formulae outside of the release process, they should know enough about the release process to know that they should just copy the bump commands from the workflow.
• Limit pathways, prevent bad values, & make config more explicit, e.g.:
  • shell scripts should accept only arguments, not environment variables.
  • Release workflows & shell scripts should:
    • Require that the release tag is a properly formatted version tag.
    • Checkout the release version tag, then use that version tag as the source for the version & for the git revision.
    • Not accept arguments, environment variables, or anything else to specify version, tag, branch, revision, etc.
• Replace script/version --write & script/version_bump with script/generate_version_info_for_swift
• When working locally, versions used (e.g. in Sources/mas/Package.swift) for revisions that aren't directly tagged with a version tag are now specified by the full git describe --tags output, which includes the current revision & the number of commits since the tag.
• Merge all release.yml jobs into one.
• shell script cleanup:
  • Migrate from bash to zsh.
  • Standardize settings at beginning of scripts using .
    • Prevent some external settings from affecting scripts.
    • cd into project root at beginning of every script.
  • Use -Ndfgku in all shebangs (add -e to all shebangs except for lint's).
  • Lowercase all non-environment variables.
  • Quote as appropriate.
  • Include braces in all variable uses.
  • Use printf instead of echo.
  • Write to stderr where appropriate.
  • Inline single-use variables.
  • Improve script outputs.
  • Simplify & standardize scripts.
  • Use more zsh builtins instead of external commands.
• Fix informational URLs throughout repo:
  • Replace redirecting links.
  • Remove defunct links.
  • http -> http.
• Ensure all files have one & only one trailing newline, and no leading newlines.
• Minor Swift cleanups.
• Improve documentation & samples.
• Improve & simplify .editorconfig.
• Upgrade danger-swift from 3.18.0 to 3.20.2.
• Suppress script/test boilerplate output.
• Fix mas-cli/tap/mas tap URLs.
• Remove .actrc & act brew dependency

Resolve:

• Ensure shell scripts aren't unduly influenced by external environment #658
• Replace uses of commands that are not shell builtins #656
• Switch all scripts from bash to zsh #654
• Cannot build 1.8.7+ on macOS < 12.3 because readlink doesn't accept -f flag #636
• 1.8.7 GitHub Release & Homebrew custom tap binaries are arm64 instead of universal #635
• Custom Homebrew tap has incorrect versions in bottle URLs #634
• Suppress successful test output from script/test #628