diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f6f763dd..ec363539 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -90,6 +90,8 @@ jobs: run: shellcheck -S warning tools/ci/*.sh tools/release/*.sh tools/*.sh - name: Change detection (tools/ci/changes.sh) run: tools/ci/test-changes.sh + - name: Release notes extraction + run: tools/release/test-changelog-notes.sh - name: Release scanner lookup (tools/release/find-scanner.sh) run: tools/release/test-find-scanner.sh - name: Agent skills diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ce38424b..b2d90083 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -8,10 +8,13 @@ name: Release # Linux Device--linux-x86_64.tar.gz # Device--linux-aarch64.tar.gz # -# Releasing: set `version` in the root Cargo.toml to X.Y.Z, merge that to main, then push -# the tag vX.Y.Z on that commit. The tag must be on main and match Cargo.toml, or nothing -# builds. The release is created as a draft with generated notes; review the packages and -# publish it by hand. +# Releasing (docs/building.md > Versions and releases): a release PR sets `version` in the +# root Cargo.toml to X.Y.Z (SemVer, 0.x while pre-alpha; X.Y.Z-alpha.N, -beta.N or -rc.N for a +# pre-release) and moves CHANGELOG.md's Unreleased entries under `## [X.Y.Z] - date`. Merge it, +# then push the tag vX.Y.Z on that commit. The tag must be on main, match Cargo.toml and have a +# changelog section, or nothing builds. The release is created as a draft whose notes are that +# section followed by GitHub's generated list of pull requests; a pre-release version is +# marked as a pre-release. Review the packages and publish it by hand. # # Other runs build the packages without releasing anything (download them from the run's # artifacts): @@ -73,6 +76,12 @@ jobs: echo "::error::tag $GITHUB_REF_NAME does not match the Cargo.toml version $version" exit 1 fi + if ! [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-(alpha|beta|rc)\.[0-9]+)?$ ]]; then + echo "::error::version $version is not X.Y.Z or X.Y.Z-alpha.N / -beta.N / -rc.N" + exit 1 + fi + bash tools/release/changelog-notes.sh "$version" > /dev/null \ + || { echo "::error::CHANGELOG.md has no section for $version"; exit 1; } git fetch --no-tags origin main:refs/remotes/origin/main if ! git merge-base --is-ancestor "$GITHUB_SHA" refs/remotes/origin/main; then echo "::error::tag $GITHUB_REF_NAME is not on main; releases are built from main only" @@ -393,6 +402,12 @@ jobs: id-token: write # sign the build provenance (Sigstore, through GitHub's OIDC token) attestations: write # store the provenance with the repository steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + sparse-checkout: | + CHANGELOG.md + tools/release - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 with: path: dist @@ -413,10 +428,17 @@ jobs: - name: Create the draft release env: GH_TOKEN: ${{ github.token }} + VERSION: ${{ needs.version.outputs.version }} run: | + # The changelog section first; --generate-notes appends GitHub's list of pull requests. + bash tools/release/changelog-notes.sh "$VERSION" > "$RUNNER_TEMP/notes.md" + prerelease=() + case "$VERSION" in *-*) prerelease=(--prerelease) ;; esac gh release create "$GITHUB_REF_NAME" dist/* \ --repo "$GITHUB_REPOSITORY" \ --draft \ - --title "Device ${{ needs.version.outputs.version }}" \ + "${prerelease[@]}" \ + --title "Device $VERSION" \ + --notes-file "$RUNNER_TEMP/notes.md" \ --generate-notes \ --verify-tag diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..e87660b1 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,26 @@ +# Changelog + +All notable changes to Device, by release. The format follows +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow +[Semantic Versioning](https://semver.org/) with `0.x` while Device is pre-alpha: a minor bump (0.2.0) for new +features or anything that breaks older projects, a patch bump (0.1.1) for fixes only. Pre-releases are tagged +`-alpha.N`, `-beta.N` or `-rc.N`. How a release is made is in [docs/building.md](docs/building.md#versions-and-releases). + +Add a line under **Unreleased** in the same pull request as any change a user would notice, under Added, Changed, +Fixed or Removed. Write it for people who use Device, not for developers. + +## [Unreleased] + +Nothing has been released yet. The first release, 0.1.0, will cover what is on `main` today: + +### Added + +- Timeline with audio and MIDI clips, fades, looping, a metronome, and tempo, time signature and key in the transport. +- Piano roll with a velocity lane, quantize, transpose and humanize. +- Audio recording with measured latency compensation, count-in and loop takes; MIDI keyboard input and recording. +- Mixer with sends, return tracks, group tracks, and a channel strip trim, width and mono switch. +- Built-in instruments (synth, sampler, drum rack, pad sampler) and 20 built-in effects, an LFO and Chains. +- AU, VST3 and CLAP plugin hosting with an out-of-process scanner and delay compensation. +- Automation for every device control and the channel strip. +- Export to WAV or MP3 (mix or stems, whole song or loop) and to an Ableton Live set with return tracks and sends. +- Undo and redo for every edit, and an optional assistant panel that uses your own Anthropic API key. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d6ee5de1..13d82ea5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,6 +51,7 @@ clang, MSVC and GCC, so please build on more than one compiler if you can, or ch - **Performance:** anything that could affect performance (especially the audio thread) includes benchmark results before and after. Extend the existing benchmarks (`engine/bench`, `crates/*/benches`) if none cover your change. The audio thread must never allocate, lock or wait. +- **Changelog:** a change users would notice adds a line under Unreleased in [CHANGELOG.md](CHANGELOG.md). - **Docs:** keep [README.md](README.md) and `docs/` accurate when your change affects what they describe (see README › Development › Keeping this README up to date). - **Original work only.** Do not paste code, artwork, icons, fonts, presets or samples from other products, and only add diff --git a/README.md b/README.md index 385dd06e..739b6420 100644 --- a/README.md +++ b/README.md @@ -180,7 +180,7 @@ decisions behind rendering, recording, plugins, delay compensation and automatio | Export | ✅ | | | Assistant | 🚧 | Tested only with a fixture provider, not yet against the live API | | Windows and Linux audio | 🚧 | Linux streams run in CI on a headless PipeWire server; neither has run on a physical sound card; no ASIO | -| Releases and branding | 🚧 | Packages are built (unsigned); code signing, original icons, a first tagged release | +| Releases and branding | 🚧 | Packages are built and macOS signing is set up; original icons, Windows signing, a first tagged release ([CHANGELOG.md](CHANGELOG.md)) | [PROGRESS.md](PROGRESS.md) has the dated, round-by-round log. diff --git a/docs/building.md b/docs/building.md index 33ee877a..54c69630 100644 --- a/docs/building.md +++ b/docs/building.md @@ -321,7 +321,7 @@ The macOS app's two architectures build side by side on separate runners and are joined with `lipo` in a third job. Each package carries the plugin scanner next to the app, where the app looks for it first, and is smoke-tested on its runner (installed, then started to render a screenshot). Pushing a tag `vX.Y.Z` builds them from `main` and -creates a **draft** GitHub release with generated notes, a `SHA256SUMS.txt` and +creates a **draft** GitHub release (see [Versions and releases](#versions-and-releases)), a `SHA256SUMS.txt` and a signed build provenance attestation for every package (check a download with `gh attestation verify --repo devicedaw/device`); the tag must match the `version` in the root `Cargo.toml`. A manual run (Actions › Release › Run @@ -343,6 +343,34 @@ first launch. The Windows packages are not signed yet, so SmartScreen warns on first run. The packaging scripts are in [`tools/release/`](../tools/release/). +### Versions and releases + +Device uses [Semantic Versioning](https://semver.org/), staying on `0.x` while it is pre-alpha: + +- **Minor** (`0.1.0` to `0.2.0`): new features, or a change that breaks projects saved by an older version. +- **Patch** (`0.1.0` to `0.1.1`): fixes only. +- **Pre-releases**: `0.2.0-alpha.1`, `-beta.N` or `-rc.N`. They are published as GitHub pre-releases. + +The app version is the `version` in the root `Cargo.toml` (every crate shares it). The project file format has its +own version number and changes only when the file format does, independently of the app version. + +[`CHANGELOG.md`](../CHANGELOG.md) is the user-facing list of changes, in +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) style. A pull request with a change users would notice +adds a line under **Unreleased**. [`PROGRESS.md`](../PROGRESS.md) stays the detailed development log. + +To release: + +1. Open a release pull request that sets `version` in `Cargo.toml` (run `cargo check` so `Cargo.lock` follows) and + moves the Unreleased entries under a new `## [X.Y.Z] - YYYY-MM-DD` heading in `CHANGELOG.md`. +2. Merge it, then tag that commit on `main` and push the tag: `git tag vX.Y.Z && git push origin vX.Y.Z`. +3. The Release workflow checks that the tag matches `Cargo.toml`, is on `main` and has a changelog section, builds + and signs the packages (the macOS signing job waits for approval in the `release` environment), and creates a + draft release. Its notes are the changelog section followed by GitHub's generated list of pull requests. +4. Review the draft and its packages, then publish it. + +The section for the notes is extracted by [`tools/release/changelog-notes.sh`](../tools/release/changelog-notes.sh), +tested in CI by `tools/release/test-changelog-notes.sh`. + ### Compatibility names The public app name is **Device**. The command-line executable remains `device-studio` and diff --git a/tools/release/changelog-notes.sh b/tools/release/changelog-notes.sh new file mode 100755 index 00000000..ec0b9475 --- /dev/null +++ b/tools/release/changelog-notes.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +# Prints the CHANGELOG.md section for one version, for the release notes. +# +# tools/release/changelog-notes.sh 0.2.0 [CHANGELOG.md] +# +# The section is everything between its heading `## [0.2.0]` (a date may follow) and the next +# `## ` heading, with leading and trailing blank lines trimmed. Fails when the version has no +# section or the section is empty, so a release can't go out without notes. +# Test it with tools/release/test-changelog-notes.sh. +set -euo pipefail + +version=${1:?usage: changelog-notes.sh VERSION [CHANGELOG.md]} +file=${2:-CHANGELOG.md} +[ -f "$file" ] || { echo "error: $file not found" >&2; exit 1; } + +notes=$(awk -v v="$version" ' + /^## / { + if (found) exit + heading = $0 + sub(/^## +/, "", heading) + if (index(heading, "[" v "]") == 1) { found = 1; next } + } + found { print } +' "$file" | sed -e '/./,$!d' | sed -e ':a' -e '/^\n*$/{$d;N;ba' -e '}') + +if [ -z "${notes//[[:space:]]/}" ]; then + echo "error: $file has no notes for $version (add a '## [$version] - YYYY-MM-DD' section)" >&2 + exit 1 +fi +printf '%s\n' "$notes" diff --git a/tools/release/test-changelog-notes.sh b/tools/release/test-changelog-notes.sh new file mode 100755 index 00000000..ae734619 --- /dev/null +++ b/tools/release/test-changelog-notes.sh @@ -0,0 +1,46 @@ +#!/usr/bin/env bash +# Tests tools/release/changelog-notes.sh against a small changelog. +set -euo pipefail +here=$(cd "$(dirname "$0")" && pwd) +tmp=$(mktemp -d) +trap 'rm -rf "$tmp"' EXIT + +cat > "$tmp/CHANGELOG.md" <<'MD' +# Changelog + +## [Unreleased] + +- Not out yet. + +## [0.2.0-alpha.1] - 2026-12-01 + +### Added + +- Pre-release feature. + +## [0.1.0] - 2026-11-20 + +- First release. + +## [0.0.9] + +MD + +fail=0 +check() { # name, expected output, version + local got + got=$(bash "$here/changelog-notes.sh" "$3" "$tmp/CHANGELOG.md" 2>/dev/null) || got="" + if [ "$got" != "$2" ]; then + echo "FAIL $1: got [$got]" + fail=1 + fi +} +check "a dated section" "- First release." 0.1.0 +check "a pre-release with subheadings" "### Added + +- Pre-release feature." 0.2.0-alpha.1 +check "no section" "" 0.3.0 +check "an empty section" "" 0.0.9 +check "a prefix of another version" "" 0.2.0 +[ "$fail" = 0 ] && echo "changelog-notes: all checks passed" +exit "$fail"