Skip to content

release.md

Latest commit

 

History

History
84 lines (63 loc) · 3.79 KB

release.md

File metadata and controls

84 lines (63 loc) · 3.79 KB
last_reviewed 2026-03-28

Release Reference

Versioning Contract

  • MARKETING_VERSION is the user-facing product version.
  • CURRENT_PROJECT_VERSION is the build number.
  • MARKETING_VERSION should always use major.minor.patch format, for example 0.2.0.
  • CURRENT_PROJECT_VERSION should be a monotonically increasing integer, for example 3.
  • GitHub prerelease tags should use v<MARKETING_VERSION>-beta.<CURRENT_PROJECT_VERSION>.
  • GitHub prerelease titles should use Hypnograph <MARKETING_VERSION> beta <CURRENT_PROJECT_VERSION>.
  • Unsigned artifact names use Hypnograph-<MARKETING_VERSION>-<CURRENT_PROJECT_VERSION>-macOS-unsigned.

This maps the Xcode settings cleanly to Apple bundle version fields:

  • MARKETING_VERSION -> CFBundleShortVersionString
  • CURRENT_PROJECT_VERSION -> CFBundleVersion

Tooling note:

  • agvtool was evaluated, but the current project shape does not make it a clean fit.
  • In this repo it reports ambiguous build versions across targets and attempts to update missing/generated Info.plist paths for some targets.
  • For now, version bumps are handled by scripts/bump-version.sh so the release line stays explicit and predictable.

Build Unsigned

To build unsigned artifacts locally without publishing:

  1. Open Hypnograph.xcodeproj in Xcode.
  2. Verify the Hypnograph target builds in Release.
  3. From repo root, run ./scripts/build-unsigned.sh.

This writes the unsigned .dmg, .zip, and .sha256 files into dist/.

dist/ is local build/release staging only. Those artifacts are uploaded directly to GitHub Releases by scripts/release-unsigned.sh and should not be committed to the repository.

Prepare Release Version

Recommended beta release preparation:

  1. Confirm the working tree is in a state you want to release from.
  2. Run ./scripts/bump-version.sh --commit --tag.
  3. This increments CURRENT_PROJECT_VERSION by default, commits the version change, and creates the matching beta tag.

Options:

  • --marketing-version <x.y.z> to change the release line and reset the build number to 1 unless --build-number is also provided
  • --build-number <n> to set a specific build number
  • --commit to create the version-bump commit
  • --tag to create the matching beta tag after committing

Release Unsigned To GitHub

To build and publish the current unsigned beta release to GitHub Releases:

  1. Open Hypnograph.xcodeproj in Xcode.
  2. Confirm MARKETING_VERSION and CURRENT_PROJECT_VERSION are correct.
  3. Authenticate GitHub CLI with gh auth login if needed.
  4. From repo root, run ./scripts/release-unsigned.sh.

Optional flags:

  • --skip-build to publish existing artifacts already present in dist/
  • --draft to create or update the release as a draft
  • --notes-file <path> to provide custom release notes
  • --previous-tag <tag> to override which previous tag is used for generated notes
  • --tag <tag> to override the default tag
  • --title <title> to override the default release title

Default release notes behavior:

  • If --notes-file is not provided, the script generates notes from commit subjects since the previous v* tag.
  • If needed, --previous-tag can be used to choose a different comparison point.
  • This project is not currently using Conventional Commits or GitHub autogenerated release notes as the default release-notes source.

Generated artifacts:

  • Hypnograph-<version>-<build>-macOS-unsigned.dmg
  • Hypnograph-<version>-<build>-macOS-unsigned.zip
  • Hypnograph-<version>-<build>-macOS-unsigned.sha256

Notes:

  • dist/ remains local staging and should stay uncommitted.
  • This path does not use TestFlight or notarization.
  • Gatekeeper will show a warning because the app is unsigned and not notarized.
  • This is the current direct-download beta path when Apple Developer Program distribution is not being used.