Improve release process

[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 probably best to split the release process into stages:

Stage 1: Generate Draft

Somehow start a process that creates a GitHub Release draft, and that, while still a draft, performs all the other release steps except for bumping the homebrew-core mas formula & except for labelling / approving the bump PR for the mas-cli/tap/mas formula.

We should support only one way to start this stage. Start options include:

• 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.
  • This seems the best option to me.
• When a draft release is made manually via the GitHub web or cli interface
  • This would require validating the tag name, prerelease setting, etc.

This stage would:

• Validate inputs (like version tag)
• Checkout the version tag
• Bootstrap
• Build
• Package the *.pkg(s)
• Create a GitHub Release draft which would:
  • Be a prerelease if the version tag contains a -
  • Have autogenerated release notes
• Upload the *.pkg(s) to the draft
• Create a mas-cli/tap/mas formula bump PR

Stage 2: Manual Draft Inspection / Modification

This step could be skipped, but I advise against it. If skipped, stages 1 & 3 could be combined into one continuous script.

The releaser inspects everything created in stage 1, including the GitHub Releases draft (including the generated release notes) & related external PRs. 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 from stage 2, then an on: release: types: deleted workflow will close the related external PRs.

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

• Approve / apply the pr-pull label to the mas-cli/tap/mas formula bump PR, which will generate bottles for the custom tap in

  • Generate for macOS 12 & older.
  • Generate for Intel & Apple Silicon, where appropriate.
  • Store in mas-cli/mas GitHub Releases.

• Bump the homebrew-core mas formula.

Tag Type

Should we use lightweight or annotated tags for versions?

Briefly noted in #655.

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 tag-related proposals.

Details

The general principle of this issue is simplicity:

• Remove extraneous files from mas-cli/mas repo:
  • Makefile
  • .github/event.json
  • Many bash 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 bash 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.:
  • bash scripts should accept only arguments, not environment variables.
  • Release workflows & bash 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.
• bash script cleanup:
  • cd into project root at beginning of every bash script.
  • Use -u in all bash shebangs.
  • Lowercase all bash 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.
• 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.

Improvements that are being worked on:

• Instead of automatically running the release workflow when a release is published, manually run the release workflow, which will:
  • Ensure that the given release tag argument is a correctly formatted version tag.
  • Create a draft release.
  • Stop progressing if any step fails.
    • Hopefully will revert prior steps if any step fails.
  • Skip steps that should be skipped for prereleases (like bumping homebrew-core formula).
  • If all succeeds, the draft release will be changed to a public release.
  • Automatically approve / label with pr-pull custom tap bump?
• Why does release.yml output release event info only when name != ''?
• mas-cli/tap/mas / GitHub Release artifacts:
  • Include version (& platform? & macOS version?) in mas.pkg filename.
  • 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?

Future tasks include:

• Cleanup actions/checkout@v4 output:
  • git config --global init.defaultBranch main
  • git config --global advice.detachedHead false
• .actrc
  • Delete?
  • Repoint --eventpath .github/event.json to a path under git-ignored .build?
• 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?
• Switch all scripts from bash to zsh #654
• GitHub branch & tag protections #655
• Replace uses of commands that are not shell builtins #656
• Use YAML & JSON schemas for validation #657

Resolve #638, #636, #635, #634, #628