ci: add CHANGELOG.md and auto-prepend new sections on release

Author: Максим Лясковский

.github/workflows/release.yml

@@ -1,15 +1,17 @@
 name: release
 
-# Trigger model: this workflow is triggered ONLY by manual dispatch.
+# Trigger model: this workflow runs ONLY by manual dispatch.
 # Click "Run workflow" in the Actions tab on GitHub.com (or run
 #   `gh workflow run release.yml -f version=2.0.1`
 # from the CLI), enter the new version, and the workflow will:
-#   1. Bump version files
-#   2. Commit + tag + push to main
-#   3. Run the test suite
-#   4. Build LinkBridge.app
-#   5. Package as a zip with ditto
-#   6. Create a draft GitHub Release with auto-generated notes
+#   1. Run the test suite
+#   2. Bump version files (linkbridge/__init__.py, setup.py)
+#   3. Generate release notes from PRs merged since the previous tag
+#   4. Prepend the new section to CHANGELOG.md
+#   5. Commit (version bump + changelog) + tag + push to main
+#   6. Build LinkBridge.app
+#   7. Package as a zip with ditto
+#   8. Create a draft GitHub Release with the same notes and the .zip
 on:
   workflow_dispatch:
     inputs:
@@ -30,7 +32,8 @@ jobs:
         uses: actions/checkout@v4
         with:
           ref: main
-          fetch-depth: 0  # full history so auto-generated release notes can diff against the previous tag
+          fetch-depth: 0     # full history so we can see previous tags
+          fetch-tags: true   # explicitly pull tags so `git describe` works
 
       - name: Configure git identity
         run: |
@@ -54,12 +57,43 @@ jobs:
       - name: Bump version files
         run: venv/bin/bump-my-version replace --new-version "${{ inputs.version }}"
 
-      - name: Show diff after bump
+      - name: Show diff after version bump
         run: git diff
 
+      - name: Generate release notes from previous tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+          echo "previous tag: ${PREV_TAG:-<none>}"
+
+          if [[ -z "$PREV_TAG" ]]; then
+            gh api -X POST "repos/${{ github.repository }}/releases/generate-notes" \
+              -f tag_name="v${{ inputs.version }}" \
+              -f target_commitish="main" \
+              --jq '.body' > release-notes.md
+          else
+            gh api -X POST "repos/${{ github.repository }}/releases/generate-notes" \
+              -f tag_name="v${{ inputs.version }}" \
+              -f previous_tag_name="$PREV_TAG" \
+              -f target_commitish="main" \
+              --jq '.body' > release-notes.md
+          fi
+
+          echo "--- generated notes ---"
+          cat release-notes.md
+          echo "--- end notes ---"
+
+      - name: Prepend new section to CHANGELOG.md
+        run: |
+          venv/bin/python scripts/update_changelog.py \
+            "${{ inputs.version }}" \
+            "$(date -u +%Y-%m-%d)" \
+            release-notes.md
+
       - name: Commit, tag, push
         run: |
-          git add linkbridge/__init__.py setup.py
+          git add linkbridge/__init__.py setup.py CHANGELOG.md
           git commit -m "chore: release v${{ inputs.version }}"
           git tag -a "v${{ inputs.version }}" -m "Release v${{ inputs.version }}"
           git push origin main
@@ -81,6 +115,6 @@ jobs:
           gh release create "v${{ inputs.version }}" \
             --repo "${{ github.repository }}" \
             --title "LinkBridge v${{ inputs.version }}" \
-            --generate-notes \
+            --notes-file release-notes.md \
             --draft \
             "dist/LinkBridge-v${{ inputs.version }}.zip"

CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to LinkBridge are documented here, in reverse
+chronological order. From v2.0.1 onwards, new entries are appended
+automatically by the [`release.yml`](.github/workflows/release.yml)
+workflow on each release — they list every pull request merged since
+the previous version. The v2.0.0 entry below was hand-written because
+it predates the automation.
+
+The format roughly follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!-- changelog-insertion-point -->
+
+## [v2.0.0](https://github.com/AnyByte/LinkBridge/releases/tag/v2.0.0) — 2026-04-09 — macOS port
+
+Initial macOS port release. Replaces the original Linux/ALSA implementation
+with a pure-Python macOS menu bar app. The Linux sources are archived under
+`legacy/` and are no longer maintained.
+
+### What's Changed
+
+- Merge macOS port ([#1](https://github.com/AnyByte/LinkBridge/pull/1)) — full rewrite for macOS, packaged as `LinkBridge.app`
+
+### Highlights
+
+- Pure-Python menu bar app built on `rumps` (no native code of our own)
+- Bidirectional MIDI via `mido` + `python-rtmidi` over CoreMIDI
+- 24 ppqn clock generator with drift-compensated absolute-time scheduling
+- Reactive Ableton Link integration via `aalink` callbacks (no polling)
+- Settings persistence at `~/Library/Application Support/LinkBridge/settings.json`
+- Distributed as a double-clickable `LinkBridge.app` bundle (custom icon, `LSUIElement`)
+- 22 unit tests covering Settings, MidiOutput, and ClockEngine
+- py2app build via `./scripts/build_app.sh`
+- GitHub Actions CI: tests on every PR, releases via `workflow_dispatch`
+
+### Compatibility
+
+Works with any host that broadcasts Ableton Link tempo: djay Pro, Mixxx,
+Ableton Live, Logic Pro, GarageBand. **Rekordbox 7.x** has a one-way Link
+integration, so manual tempo entry in the Link sub-window is required —
+see the [README](README.md) for the workflow.

README.md

@@ -233,7 +233,11 @@ gh run watch  # follow the build
 ```
 
 The release workflow uses [`bump-my-version`](https://github.com/callowayproject/bump-my-version)
-under the hood; the file list is in `pyproject.toml`.
+under the hood (file list in `pyproject.toml`) and prepends each new
+release section to [`CHANGELOG.md`](CHANGELOG.md) via
+`scripts/update_changelog.py`. The changelog entries are auto-generated
+from the pull requests merged since the previous tag using GitHub's
+release-notes API.
 
 ## Regenerating the app icon
 

scripts/update_changelog.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Prepend a new release section to CHANGELOG.md.
+
+Reads release notes from a markdown file (typically generated by GitHub's
+`/repos/{owner}/{repo}/releases/generate-notes` API) and inserts them as a
+new section in CHANGELOG.md, immediately after the
+`<!-- changelog-insertion-point -->` marker. The marker stays in place so
+the next release can insert above the previous one, keeping CHANGELOG.md
+in reverse chronological order.
+
+Usage:
+    update_changelog.py <version> <date> <notes-file>
+
+Example:
+    update_changelog.py 2.0.1 2026-05-01 release-notes.md
+
+Behavior:
+    - Errors out if CHANGELOG.md doesn't exist or has no insertion marker
+    - Errors out if a section for this version already exists (idempotency
+      guard so the workflow can't accidentally double-write the changelog)
+    - Wraps the version in a markdown link to the GitHub release page so
+      readers can jump straight to the release for downloads
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+CHANGELOG = REPO / "CHANGELOG.md"
+INSERTION_MARKER = "<!-- changelog-insertion-point -->"
+RELEASES_URL = "https://github.com/AnyByte/LinkBridge/releases/tag"
+
+
+def main() -> int:
+    if len(sys.argv) != 4:
+        print(__doc__, file=sys.stderr)
+        return 2
+
+    version, date, notes_path = sys.argv[1], sys.argv[2], Path(sys.argv[3])
+
+    if not CHANGELOG.exists():
+        print(f"error: {CHANGELOG} not found", file=sys.stderr)
+        return 1
+    if not notes_path.exists():
+        print(f"error: notes file {notes_path} not found", file=sys.stderr)
+        return 1
+
+    notes = notes_path.read_text(encoding="utf-8").strip()
+    if not notes:
+        print(f"error: notes file {notes_path} is empty", file=sys.stderr)
+        return 1
+
+    changelog = CHANGELOG.read_text(encoding="utf-8")
+
+    if INSERTION_MARKER not in changelog:
+        print(
+            f"error: insertion marker {INSERTION_MARKER!r} not found in {CHANGELOG}",
+            file=sys.stderr,
+        )
+        return 1
+
+    section_header = f"## [v{version}]({RELEASES_URL}/v{version}) — {date}"
+    if section_header in changelog:
+        print(
+            f"error: section for v{version} already exists in {CHANGELOG}",
+            file=sys.stderr,
+        )
+        return 1
+
+    new_section = f"\n\n{section_header}\n\n{notes}\n"
+
+    updated = changelog.replace(
+        INSERTION_MARKER,
+        f"{INSERTION_MARKER}{new_section}",
+        1,
+    )
+
+    CHANGELOG.write_text(updated, encoding="utf-8")
+    print(f"prepended v{version} section to {CHANGELOG.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())