> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
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.