Skip to content

armgit / nota

Public Imported from GitHub
0

Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.

(feat) Release notes list every change, its commit and the contributors (#283)

Egor Khindikaynene0afaf237775
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
index 5ee55963..8c85be7e 100644
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@@ -16,13 +16,15 @@ Two files describe a release, for two readers:
- **`release-notes/X.Y.Z.en.md`** and **`release-notes/X.Y.Z.ru.md`** are the curated
text: summarised, deduplicated, checked against the code. **Everything published comes
from them**, and the app bundles the EN file for its What's New window, so the notes must
- be committed on the release branch before the tag is built. `scripts/release-notes.sh X.Y.Z <target>` renders them for each place:
+ be committed on the release branch before the tag is built. They hold a summary, the
+ full Added / Changed / Fixed list with a commit link on each item, and the contributors
+ (format in P4). `scripts/release-notes.sh X.Y.Z <target>` renders them for each place:
- | target | where it goes |
- |-----------|-------------------------------------------------|
- | `github` | GitHub release body (the workflow uses this) |
- | `post-en` | English news channels |
- | `post-ru` | Russian news channels |
+ | target | where it goes | full list |
+ |-----------|-------------------------------------------------|-----------|
+ | `github` | GitHub release body (the workflow uses this) | yes |
+ | `post-en` | English news channels | no |
+ | `post-ru` | Russian news channels | no |
The release runs through the branches like this. **The user does every commit, push and PR
by hand.** This skill never commits, pushes or opens a PR (see the user-commits rule).
@@ -81,18 +83,44 @@ are.
### P4. Write the curated notes, EN and RU
This is the main work of the phase. Create `release-notes/X.Y.Z.en.md` and
-`release-notes/X.Y.Z.ru.md`.
-
-1. **Gather.** Read the whole `[X.Y.Z]` section you just promoted, then
- `git log --oneline <prev-tag>..HEAD` (previous tag:
- `git describe --tags --abbrev=0 --match 'v*'`).
+`release-notes/X.Y.Z.ru.md`. Each has four parts, in this order:
+
+1. **Summary**: the lede and the numbered headline features, for someone who reads only
+ this part.
+2. **Full list**: every user-facing change of the release, grouped as Added / Changed /
+ Fixed / Removed.
+3. **Commit links**: each full-list item ends with a link to its commit.
+4. **Contributors**: everyone who has a commit in the release, linked to their GitHub
+ profile.
+
+Steps:
+
+1. **Gather.**
+ - The previous tag is the highest version tag:
+ `git tag --list 'v*' --sort=-v:refname | head -1`. Don't use `git describe` on
+ `develop`: release tags sit on `main`'s merge commits, which `develop` doesn't
+ contain, so `describe` returns a tag several releases old.
+ - Read the whole `[X.Y.Z]` section you just promoted.
+ - `scripts/release-credits.sh <prev-tag> origin/develop commits` lists every commit of
+ the release (short sha, sha, subject). It's the checklist for the full list.
+ - `scripts/release-credits.sh <prev-tag> origin/develop contributors` prints the
+ ready Contributors line. It asks GitHub for every commit's authors and co-authors
+ (needs `gh` signed in) and leaves out bots and AI co-authors.
2. **Reconcile.** Merge entries that describe the same thing. Where entries conflict (a
shortcut reassigned twice, a feature added and then reworked), **the code decides**:
read the handler, the default or the UI and describe what ships. Drop anything that
- was added and then removed within the same release, and leave out internal or
- mechanical changes (refactors, CI, tests) unless a user can feel them.
-3. **Write.** Each language natively, not as a translation. Format (bold titles and `•`
- bullets, no `#` headings, so the text pastes into Telegram as-is):
+ was added and then removed within the same release. Then build the full list from the
+ commits:
+ - Each user-facing change is one item, linked to the commit(s) that brought it. A fix
+ and its follow-up make one item with both links.
+ - Leave out internal or mechanical commits (refactors, CI, tests, release chores)
+ unless a user can feel them. Their authors are still contributors.
+ - Walk the `commits` output once more at the end: every user-facing commit must be in
+ an item.
+3. **Write.** Each language natively, not as a translation. Format: bold titles and `•`
+ bullets, no `#` headings, so the text pastes into Telegram as is. The two comment
+ markers say where the full list and the contributors start, whatever the language.
+ They are invisible on GitHub, and `release-notes.sh` strips them.
```
<!-- SPDX-License-Identifier: AGPL-3.0-only -->
@@ -104,17 +132,56 @@ This is the main work of the phase. Create `release-notes/X.Y.Z.en.md` and
**2. Next feature**
…
- **Also**
- • visual changes, notable fixes, small conveniences, one line each
- • any behaviour change users must know: a moved or removed shortcut, a changed default
+ <!-- changes -->
+ **Added**
+ • A new capability, one line ([a1b2c3d](https://github.com/nota-daw/nota/commit/<full sha>))
+
+ **Changed**
+ • A behaviour users must know: a moved shortcut, a changed default ([e4f5a6b](…), [c7d8e9f](…))
+
+ **Fixed**
+ • What no longer goes wrong, said from the user's side ([0a1b2c3](…))
+
+ **Removed**
+ • …
+
+ <!-- contributors -->
+ **Contributors**
+ [@login](https://github.com/login), [@other](https://github.com/other)
```
- Rank the sections by importance. A patch release can be just the lede plus **Also**.
- Leave out the title and the download link, because `release-notes.sh` adds them per
- target. Use the user's product language: "track", "device card", "piano roll", not class
- names.
-4. Show the user both rendered posts (`scripts/release-notes.sh X.Y.Z post-en`, `post-ru`)
- and iterate until they approve. The rest of the release depends on this text.
+ Rules for the format:
+ - Rank the summary's sections by importance. A patch release can have just the lede
+ before the full list.
+ - Groups go in the order Added, Changed, Fixed, Removed; leave out empty groups.
+ Inside a group, put the most noticeable changes first.
+ - A commit link's text is the 7-character short sha and its URL takes the full sha
+ from the `commits` output. These are `develop`'s squash commits. They become part of
+ `main` through the develop → main merge, so the links keep working after the release.
+ - New notes have no **Also** block: the full list replaces it, so nothing is listed
+ twice.
+ - RU titles: **Добавлено**, **Изменено**, **Исправлено**, **Удалено**, **Участники**.
+ The EN and RU files have the same groups, the items in the same order with the same
+ links, and the same contributors.
+ - Contributors: paste the `contributors` line. Resolve every `warn:` line it printed
+ on stderr:
+ - An author with no GitHub login can be a second address of someone already listed
+ (the user's work email, for example). Drop that name.
+ - Otherwise, find the login and link it, or keep the plain name.
+ - Don't add or remove people by hand otherwise.
+ - Leave out the title and the download link, because `release-notes.sh` adds them per
+ target. Use the user's product language: "track", "device card", "piano roll", not
+ class names.
+4. Show the user the three renders and iterate until they approve. The rest of the
+ release depends on this text.
+ - `scripts/release-notes.sh X.Y.Z github` has all four parts.
+ - `post-en` and `post-ru` have the summary and the contributors but no full list. A
+ Telegram message holds 4096 characters, and the posts end with the link to the
+ GitHub release, which has the full list.
+
+ The app bundles the EN file. What's New shows the summary, then "All changes" with the
+ groups, then the contributors, and the links in it are clickable. The smoke test checks
+ that every full-list item of a shipped notes file ends in a commit link.
### P5. Bump the versions
@@ -164,8 +231,8 @@ Don't commit. Give the user:
- the **PR into develop**: title `(chore) Release X.Y.Z` (it becomes the squash commit
message), body = a short list of the changed files,
- the **PR text** for develop → main, opened after the first one is merged. Title
- `Release X.Y.Z`, body = the output of `scripts/release-notes.sh X.Y.Z github`, so the
- reviewer reads exactly what will be published. Merge it with **Create a merge commit**
+ `Release X.Y.Z`, body = the output of `scripts/release-notes.sh X.Y.Z github` (summary,
+ full list and contributors), so the reviewer reads exactly what will be published. Merge it with **Create a merge commit**
(the only method `main` allows),
- the image path and any docs gaps,
- the next step: merge both PRs once CI is green, then run `/release tag`.
@@ -216,5 +283,7 @@ already has `develop` as a parent.
`release-notes/`.
- Don't write published text anywhere except `release-notes/`. GitHub and the channels
must come from the same files.
+- Don't type the contributors or commit shas from memory. Take them from
+ `scripts/release-credits.sh`, and resolve its warnings instead of ignoring them.
- Don't bump only one of app or engine, and don't reset a component to 0.
- Don't hard-code the date or reuse an existing version or tag.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2ea0273a..bc7cf9f4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -97,6 +97,11 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.
**Check now** button. Nothing downloads until you click Update.
### Changed
+- **Release notes list every change and who made it**: from the next release on, What's New
+ shows a release's summary, then **All changes**, the full Added / Changed / Fixed list with
+ each item's commit, then the release's contributors. Links in What's New open in the
+ browser. The GitHub release carries the same text; the news posts keep the summary and the
+ contributors.
- **The clip editor ruler shows where the clip sits** (nota-daw/nota#275): with one MIDI or
audio clip open, the ruler reads the clip's arrangement position — a clip at bar 9 starts
at 9, not 1 — as a multi-clip selection already did. Unwarped audio clips read in bars too.
diff --git a/FEATURES.md b/FEATURES.md
index cc46960d..cb21c628 100644
--- a/FEATURES.md
+++ b/FEATURES.md
@@ -1117,7 +1117,9 @@ audio effects after it keep running and keep their settings; saved with the proj
- **What's New** — a window showing the release notes (`release-notes/X.Y.Z.en.md`, the GitHub
release text; the CHANGELOG section for versions without them) newer than `LastSeenVersion`, once
after the first launch on a new version; any time from Help ▸ What's New or the version
- number in the status bar.
+ number in the status bar. A release's notes give a summary, then All changes (Added /
+ Changed / Fixed, each item linked to its commit), then the contributors; links open in the
+ browser.
- **Self-update** — Nota looks for a newer GitHub release on every launch and once a day while
it runs (Settings ▸ Updates turns that off), and on demand from Help ▸ Check for updates…
(also in the macOS app menu), which also says when you're up to date or couldn't check. A
diff --git a/scripts/release-credits.sh b/scripts/release-credits.sh
new file mode 100755
index 00000000..f46f6c41
--- /dev/null
+++ b/scripts/release-credits.sh
@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: AGPL-3.0-only
+#
+# What /release needs to write the full change list and the contributors of a release
+# (release-notes/X.Y.Z.{en,ru}.md, format in .claude/skills/release/SKILL.md § P4).
+#
+# Usage: scripts/release-credits.sh <from> <to> <commits|contributors>
+# e.g. scripts/release-credits.sh v0.56.1 origin/develop contributors
+# commits one line per commit in <from>..<to>, oldest first: short sha, sha,
+# subject (tab-separated). Local git only.
+# contributors the ready "Contributors" line: [@login](https://github.com/login), …
+# Asks GitHub for each commit's authors, co-authors included
+# (Co-authored-by trailers), so it needs the gh CLI signed in and the
+# commits pushed. Bots and AI co-authors are left out; an author whose
+# email maps to no GitHub account is reported on stderr.
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+usage="usage: $0 <from> <to> <commits|contributors>"
+from="${1:?$usage}"
+to="${2:?$usage}"
+mode="${3:?$usage}"
+repo_owner="nota-daw"
+repo_name="nota"
+
+shas="$(git rev-list --reverse "${from}..${to}")" \
+ || { echo "error: can't list ${from}..${to}" >&2; exit 1; }
+if [ -z "$shas" ]; then
+ echo "error: no commits in ${from}..${to}" >&2
+ exit 1
+fi
+
+case "$mode" in
+ commits)
+ git log --reverse --format='%h%x09%H%x09%s' "${from}..${to}"
+ ;;
+ contributors)
+ for tool in gh jq; do
+ command -v "$tool" >/dev/null || { echo "error: $tool is not installed" >&2; exit 1; }
+ done
+
+ # One GraphQL query per 50 commits (aliases c0, c1, …); each answer is one line of
+ # JSON: the commit's authors, or {"missing":true} when GitHub doesn't have the commit
+ # (the API answers null, which gh's --jq would print as an empty line).
+ authors="$(mktemp)"
+ trap 'rm -f "$authors"' EXIT
+ batch=()
+ flush() {
+ [ "${#batch[@]}" -eq 0 ] && return
+ local q="query{repository(owner:\"${repo_owner}\",name:\"${repo_name}\"){" i=0 sha
+ for sha in "${batch[@]}"; do
+ q+="c${i}:object(oid:\"${sha}\"){...on Commit{oid authors(first:20){nodes{name email user{login}}}}} "
+ i=$((i + 1))
+ done
+ q+="}}"
+ gh api graphql -f query="$q" --jq '.data.repository | to_entries[] | (.value // {missing: true}) | tojson' >>"$authors"
+ batch=()
+ }
+ for sha in $shas; do
+ batch+=("$sha")
+ [ "${#batch[@]}" -ge 50 ] && flush
+ done
+ flush
+
+ wanted="$(printf '%s\n' "$shas" | wc -l | tr -d ' ')"
+ found="$(jq -s '[.[] | select(.oid)] | length' "$authors")"
+ if [ "$found" != "$wanted" ]; then
+ echo "error: $((wanted - found)) of ${wanted} commits in ${from}..${to} aren't on GitHub yet — push them first" >&2
+ exit 1
+ fi
+
+ # Every author of a commit counts once for it. Bots and AI co-authors (Claude signs
+ # its commits as [email protected]) aren't contributors.
+ people='[.[] | .authors.nodes | map(select(
+ (.user.login // "" | test("\\[bot\\]$|^claude$") | not)
+ and (.email // "" | ascii_downcase) != "[email protected]"))
+ | unique_by(.user.login // ("~" + (.email // .name | ascii_downcase)))[]]'
+
+ # Without a login: a second address of someone listed (same name, or a mailbox named
+ # like a login) is dropped; anyone else is listed by name and reported.
+ jq -rs "$people"' as $p
+ | ($p | map(select(.user != null))) as $known
+ | ($known | map(.user.login | ascii_downcase)) as $logins
+ | ($known | map(.name | ascii_downcase)) as $names
+ | $p | map(select(.user == null)) | unique_by(.email // .name)[]
+ | "warn: no GitHub login for \(.name) <\(.email)>"
+ + (if ((.name | ascii_downcase) as $n | $names | index($n))
+ or ((.email // "" | split("@")[0] | ascii_downcase) as $m | $logins | index($m))
+ then " (looks like a listed contributor, left out)" else "" end)' \
+ "$authors" >&2
+
+ jq -rs "$people"' as $p
+ | ($p | map(select(.user != null))) as $known
+ | ($known | map(.user.login | ascii_downcase)) as $logins
+ | ($known | map(.name | ascii_downcase)) as $names
+ | ($known | group_by(.user.login)
+ | map({key: .[0].user.login, n: length,
+ text: "[@\(.[0].user.login)](https://github.com/\(.[0].user.login))"}))
+ + ($p | map(select(.user == null)
+ | select(((.name | ascii_downcase) as $n | $names | index($n)) | not)
+ | select(((.email // "" | split("@")[0] | ascii_downcase) as $m | $logins | index($m)) | not))
+ | group_by(.name)
+ | map({key: .[0].name, n: length, text: .[0].name}))
+ | sort_by(-.n, (.key | ascii_downcase))
+ | map(.text) | join(", ")' "$authors"
+ ;;
+ *)
+ echo "error: unknown mode '$mode' (commits | contributors)" >&2
+ exit 1
+ ;;
+esac
diff --git a/scripts/release-notes.sh b/scripts/release-notes.sh
index 9d06c98d..3f94d273 100755
--- a/scripts/release-notes.sh
+++ b/scripts/release-notes.sh
@@ -2,14 +2,18 @@
# SPDX-License-Identifier: AGPL-3.0-only
#
# Renders a release's curated notes (release-notes/X.Y.Z.{en,ru}.md) for one place.
+# The notes are a summary, then (after "<!-- changes -->") the full Added / Changed /
+# Fixed list with commit links, then (after "<!-- contributors -->") the contributors.
+# The GitHub release carries all of it; the news posts leave the full list out (a
+# Telegram message holds 4096 characters) and point at the release for it.
# The one source of the published release text: the release workflow builds the GitHub
# release body with it, and /release builds the news posts with it, then checks the
# published draft against it, so the text can't drift between the places.
#
# Usage: scripts/release-notes.sh <version> <github|post-en|post-ru>
# github GitHub release body: title + EN notes + install table
-# post-en English news-channel post: title + EN notes + download link
-# post-ru Russian news-channel post: title + RU notes + download link
+# post-en English news-channel post: title + EN notes without the full list + download link
+# post-ru Russian news-channel post: title + RU notes without the full list + download link
set -euo pipefail
cd "$(dirname "$0")/.."
@@ -18,14 +22,25 @@ version="${1:?usage: $0 <version> <github|post-en|post-ru>}"
target="${2:?usage: $0 <version> <github|post-en|post-ru>}"
release_url="https://github.com/nota-daw/nota/releases/tag/v${version}"
-# The note file's body: drop the SPDX comment line and leading/trailing blank lines.
+# The note file's body: drop the comment lines (the SPDX header and the part markers)
+# and leading/trailing blank lines. "body <lang> summary" also drops the full list —
+# everything from "<!-- changes -->" up to "<!-- contributors -->" — and squeezes the
+# blank lines it leaves behind.
body() {
- local file="release-notes/${version}.$1.md"
+ local file="release-notes/${version}.$1.md" part="${2:-all}"
if [ ! -s "$file" ]; then
echo "error: $file is missing or empty" >&2
exit 1
fi
- grep -v '^<!-- SPDX-License-Identifier' "$file" | sed '/./,$!d' | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}'
+ # Markers match as in ReleaseNotesParser: alone on the line, any case, any spacing.
+ awk -v part="$part" '
+ { l = tolower($0) }
+ l ~ /^[[:space:]]*<!--[[:space:]]*changes[[:space:]]*-->[[:space:]]*$/ { if (part == "summary") skip = 1 }
+ l ~ /^[[:space:]]*<!--[[:space:]]*contributors[[:space:]]*-->[[:space:]]*$/ { skip = 0 }
+ /^[[:space:]]*<!--.*-->[[:space:]]*$/ { next }
+ skip { next }
+ { print }
+ ' "$file" | cat -s | sed '/./,$!d' | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}'
}
case "$target" in
@@ -51,11 +66,11 @@ ${en}
EOF
;;
post-en)
- en="$(body en)"
+ en="$(body en summary)"
printf '🎛 **Nota %s is out**\n\n%s\n\nDownload: %s\n' "$version" "$en" "$release_url"
;;
post-ru)
- ru="$(body ru)"
+ ru="$(body ru summary)"
printf '🎛 **Вышла Nota %s**\n\n%s\n\nСкачать: %s\n' "$version" "$ru" "$release_url"
;;
*)
diff --git a/specs/037-release-notes-full-list/checklists/requirements.md b/specs/037-release-notes-full-list/checklists/requirements.md
new file mode 100644
index 00000000..f83b18d4
--- /dev/null
+++ b/specs/037-release-notes-full-list/checklists/requirements.md
@@ -0,0 +1,36 @@
+# Specification Quality Checklist: Release notes with a full change list, commit links and contributors
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-10-22
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain (both resolved 2026-10-22)
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- The Nota Context section names files and scripts on purpose (the project's spec
+ template requires it); the requirements themselves stay at the behaviour level.
+- Items marked incomplete require spec updates before `/speckit-clarify` or `/speckit-plan`
diff --git a/specs/037-release-notes-full-list/contracts/release-notes-format.md b/specs/037-release-notes-full-list/contracts/release-notes-format.md
new file mode 100644
index 00000000..d56b08d5
--- /dev/null
+++ b/specs/037-release-notes-full-list/contracts/release-notes-format.md
@@ -0,0 +1,64 @@
+# Contract: release notes format and release scripts
+
+## 1. Notes file (example, EN)
+
+```markdown
+<!-- SPDX-License-Identifier: AGPL-3.0-only -->
+Nota 0.57 is about editing time. Copy and cut a time range across tracks, and the clip
+editors move the playhead and show arrangement bars.
+
+**1. Time ranges you can copy and cut**
+A short paragraph, as today.
+
+**2. Clip editors that follow the arrangement**
+A short paragraph.
+
+<!-- changes -->
+**Added**
+• Warp tempo next to the Warp switch, typeable, with ×2 and ÷2 ([994d0fb](https://github.com/nota-daw/nota/commit/994d0fb6…))
+
+**Changed**
+• Context menus open at their full width ([ca2d305](https://github.com/nota-daw/nota/commit/ca2d305e…))
+
+**Fixed**
+• Double-click resets knobs and sliders again ([92a0608](https://github.com/nota-daw/nota/commit/92a0608b…))
+• Aurora's heavy presets play without dropouts ([2304e1a](https://github.com/nota-daw/nota/commit/2304e1ad…))
+
+<!-- contributors -->
+**Contributors**
+[@ambertape](https://github.com/ambertape), [@rafi612](https://github.com/rafi612)
+```
+
+RU: same markers, links and order; titles «Добавлено», «Изменено», «Исправлено»,
+«Удалено», «Участники».
+
+## 2. `scripts/release-notes.sh <version> <github|post-en|post-ru>`
+
+| target | summary | full list | contributors | extra |
+|---|---|---|---|---|
+| `github` | ✓ | ✓ | ✓ | title, install table (as today) |
+| `post-en` / `post-ru` | ✓ | — | ✓ | title, download link (as today) |
+
+- All `<!-- … -->` lines are removed from every output.
+- Old-format files (no markers) render as today.
+- `release-verify.sh` is unchanged and compares the draft with the `github` output.
+
+## 3. `scripts/release-credits.sh <from> <to> <commits|contributors>` (new)
+
+- `<from>` / `<to>`: git refs; the range is `<from>..<to>` (e.g. `v0.56.1 origin/develop`).
+- `commits`: stdout, one line per commit, oldest first: `<short>\t<sha>\t<subject>`.
+ No network access.
+- `contributors`: stdout, the Contributors line (format in §1). Uses `gh api graphql`
+ against `nota-daw/nota`; needs `gh` signed in. Authors without a GitHub login are
+ printed by name and listed on stderr as `warn: no GitHub login for <name> <email>`.
+ Exit 1 with a message if `gh` is missing or a commit is not on GitHub (unpushed).
+- Never writes files.
+
+## 4. What's New (user-visible)
+
+- Summary: unchanged look.
+- Before the first `Changes` section: a 1 px divider and an "All changes" heading in the features' title style; each
+ group: `SectionLabel` title + bullets; commit links in accent colour.
+- Contributors: `SectionLabel` title + wrapped line of links.
+- Any link: hand cursor and underline on hover; click opens it in the default browser.
+- Old notes and changelog fallbacks: unchanged (links become clickable).
diff --git a/specs/037-release-notes-full-list/data-model.md b/specs/037-release-notes-full-list/data-model.md
new file mode 100644
index 00000000..0e7fd66c
--- /dev/null
+++ b/specs/037-release-notes-full-list/data-model.md
@@ -0,0 +1,56 @@
+# Data Model: Release notes with a full change list, commit links and contributors
+
+## Curated notes file (`release-notes/X.Y.Z.{en,ru}.md`)
+
+| Part | Starts at | Content | Required |
+|---|---|---|---|
+| Summary | file start (after SPDX) | lede paragraph; `**N. Title**` + paragraph sections | lede yes, sections optional |
+| Full list | `<!-- changes -->` | `**Group**` lines, each followed by `•` items | yes for new notes |
+| Contributors | `<!-- contributors -->` | `**Title**` line + one line of links/names | yes for new notes |
+
+Rules:
+
+- Markers appear at most once each, in this order; contributors never precede changes.
+- Group order: Added, Changed, Fixed, Removed; empty groups omitted. RU titles:
+ Добавлено, Изменено, Исправлено, Удалено; contributors title: Contributors / Участники.
+- No `**Also**` in new notes (the full list replaces it). Old notes: no markers, may have
+ `**Also**`.
+- EN and RU files have the same groups, items in the same order, the same commit links and
+ the same contributors.
+
+## Change item
+
+`• <text> (<commit link>[, <commit link>…])`
+
+- `<commit link>` = `[<7-char sha>](https://github.com/nota-daw/nota/commit/<40-char sha>)`.
+- The sha is a commit in the release range on `develop`.
+- One item per user-facing change; a change spread over several commits lists each.
+
+## Contributor
+
+- Source: GitHub `Commit.authors` for every commit in the range (internal ones included).
+- Identity: GitHub login; rendered `[@login](https://github.com/login)`.
+- Excluded: logins ending in `[bot]`, AI co-authors (`[email protected]`, login
+ `claude`).
+- Author without a login: plain name, flagged to the maintainer (may be a second email of
+ someone already listed — then drop it).
+- Order: most commits first, ties by login.
+
+## App model (`Changelog.cs`)
+
+```text
+ChangelogEntry(Version, Date, Sections, Lede) # unchanged
+ChangelogSection(Title, Items, Text, Kind = Feature) # + Kind
+SectionKind { Feature, Changes, Contributors }
+```
+
+Parser state transitions: start in `Feature`; `<!-- changes -->` → following sections are
+`Changes`; `<!-- contributors -->` → following sections are `Contributors`. A
+`Contributors` section's line is its `Text` (not a bullet). Changelog-fallback entries keep
+`Feature` (the window distinguishes them by `IsReleaseNotes`, as today).
+
+## Inline link (`WhatsNewWindow`)
+
+While building inlines, each `[label](url)` records `(start, length, url)` in the block's
+character space; a click whose hit-tested position falls inside a range opens `url`
+(http/https only).
diff --git a/specs/037-release-notes-full-list/plan.md b/specs/037-release-notes-full-list/plan.md
new file mode 100644
index 00000000..402e3118
--- /dev/null
+++ b/specs/037-release-notes-full-list/plan.md
@@ -0,0 +1,116 @@
+# Implementation Plan: Release notes with a full change list, commit links and contributors
+
+**Branch**: `feat/release-notes-full-list` | **Date**: 2026-10-22 | **Spec**: [spec.md](spec.md)
+
+**Input**: Feature specification from `specs/037-release-notes-full-list/spec.md`
+
+## Summary
+
+Curated release notes get two more parts after the familiar summary: a full Added /
+Changed / Fixed (/ Removed) list whose items end in commit links, and a Contributors line
+linking every human author and co-author to their GitHub profile. Two HTML-comment
+markers (`<!-- changes -->`, `<!-- contributors -->`) delimit the parts, so the format
+works in any language and old files parse unchanged. A new `scripts/release-credits.sh`
+lists the range's commits and builds the Contributors line from GitHub's GraphQL
+`Commit.authors`. `release-notes.sh` keeps all parts for GitHub and drops the full list
+from the news posts. What's New learns the section kinds, renders the full list
+expanded under an "All changes" caption, and makes every link clickable. The release skill
+§ P4 documents the new format and the gathering commands, and fixes its previous-tag
+lookup. Details: [research.md](research.md).
+
+## Nota: Read Before Planning
+
+- **UI work** → [`DESIGN.md`](../../DESIGN.md) (Studio) and the `nota-design` skill — the
+ "All changes" divider and caption, link hover state.
+- **Build / packaging** → [`BUILD.md`](../../BUILD.md) — the release scripts.
+- **Anything** → [`CONTRIBUTING.md`](../../CONTRIBUTING.md).
+
+## Technical Context
+
+**Language/Version**: C# / .NET 10 (`Nota.App`), Bash (release scripts), Markdown (skill)
+
+**Primary Dependencies**: Avalonia 12.1.4 (existing); `gh` CLI and `jq` (already used by
+`release-verify.sh`); no new dependency
+
+**Storage**: N/A — `release-notes/*.md` files; the app bundles `*.en.md` as today
+
+**Audio-Thread Impact**: None — What's New window and release tooling only.
+
+**Testing**: smoke test `--release-notes` section extended (new-format sample: kinds,
+commit-linked items, contributors; link ranges of the inline parser if split out as pure
+code); every shipped notes file still parses. Scripts checked by running them on the
+`v0.56.1..develop` range. Window checked with the headless Avalonia harness / real app per
+[quickstart.md](quickstart.md).
+
+**Target Platform**: macOS, Windows, Linux (desktop app); the release scripts run on the
+maintainer's macOS and in `release.yml` (Ubuntu)
+
+**Project Type**: desktop app + release tooling
+
+**Performance Goals**: N/A (a release has tens of commits; one GraphQL call per commit is
+fine; may batch with aliases)
+
+**Constraints**: notes stay Telegram-pasteable (no `#` headings); `release-verify.sh`
+equality with the GitHub draft unchanged; old notes render identically
+
+**Scale/Scope**: 2 C# files + 1 smoke test file, 2 scripts (1 new), the release skill, a
+CHANGELOG entry
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status |
+|---|---|
+| I. Real-time audio safety | Pass — no audio code |
+| II. Boundary discipline | Pass — no C ABI involvement |
+| III. Licensing hygiene | Pass — new script gets the SPDX header; no dependency |
+| IV. Verification gate | Pass — `scripts/build.sh`; release-notes smoke section extended |
+| V. One logical change per PR | Pass — one change: the release-notes format end to end (writer, renderer, reader) |
+| VI. Docs in sync | Planned — CHANGELOG `[Unreleased]` (Changed: What's New shows all changes, contributors, clickable links); FEATURES.md via nota-features if it lists What's New; no shortcut change |
+| VII. Spec first | Pass — spec, clarifications, this plan |
+| VIII. Rules not weakened | Pass |
+
+Post-design re-check: unchanged, all gates pass.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/037-release-notes-full-list/
+├── plan.md # this file
+├── research.md # R1–R7
+├── data-model.md # notes parts, ChangelogSection.Kind, contributor rules
+├── quickstart.md # scripts on a real range, smoke section, What's New check
+├── contracts/
+│ └── release-notes-format.md # the file format + script interfaces
+├── checklists/
+│ └── requirements.md
+└── tasks.md # /speckit-tasks
+```
+
+### Source Code (repository root)
+
+```text
+.claude/skills/release/SKILL.md # P4: four-part format, markers, gathering commands,
+ # previous tag by version (R3); P8/verify unchanged
+scripts/
+├── release-credits.sh # NEW — commits | contributors for a range (R4)
+└── release-notes.sh # strip all comments; posts drop the full list (R5)
+src/managed/Nota.App/
+├── Changelog.cs # SectionKind + ReleaseNotesParser markers (R1, R7)
+└── WhatsNewWindow.cs # kinds rendering, "All changes", clickable links (R6, R7)
+tests/Nota.SmokeTest/
+└── ReleaseNotesTests.cs # new-format sample, old sample unchanged
+CHANGELOG.md # [Unreleased] entry
+```
+
+**Structure Decision**: everything stays where the format already lives — parser in
+`Changelog.cs` (Avalonia-free, linked into the smoke test), rendering in
+`WhatsNewWindow.cs`, release tooling in `scripts/` next to `release-notes.sh`. No new
+project or folder.
+
+## Complexity Tracking
+
+None.
diff --git a/specs/037-release-notes-full-list/quickstart.md b/specs/037-release-notes-full-list/quickstart.md
new file mode 100644
index 00000000..35f5ec11
--- /dev/null
+++ b/specs/037-release-notes-full-list/quickstart.md
@@ -0,0 +1,59 @@
+# Quickstart: validating the release-notes full list
+
+Prerequisites: a built tree (`scripts/build.sh`), `gh` signed in, `jq`.
+
+## 1. Gather from a real range
+
+```bash
+scripts/release-credits.sh v0.56.1 origin/develop commits
+```
+
+Expect one line per commit since v0.56.1 (23 on 2026-10-22), oldest first.
+
+```bash
+scripts/release-credits.sh v0.56.1 origin/develop contributors
+```
+
+Expect one line with `[@login](https://github.com/login)` links — at least `ambertape` and
+`rafi612` — no `claude`, no bots; any unmapped author as a `warn:` line on stderr.
+
+## 2. Render a new-format sample
+
+Write a throwaway `release-notes/9.9.9.en.md` / `.ru.md` from
+[contracts/release-notes-format.md](contracts/release-notes-format.md) §1, then:
+
+```bash
+scripts/release-notes.sh 9.9.9 github
+```
+
+Expect summary, Added/Changed/Fixed, Contributors, install table; no `<!--` lines.
+
+```bash
+scripts/release-notes.sh 9.9.9 post-ru
+```
+
+Expect summary + «Участники» + download link, no full list. Old files
+(`scripts/release-notes.sh 0.56.1 github`) render byte-identical to before. Delete the
+9.9.9 files afterwards.
+
+## 3. Smoke test
+
+```bash
+dotnet run --project tests/Nota.SmokeTest -- --release-notes
+```
+
+Expect all checks green: old sample unchanged, new sample yields `Feature` / `Changes` /
+`Contributors` sections, every shipped notes file parses.
+
+## 4. What's New
+
+Bundle the 9.9.9 sample (or point the headless harness at it, see the UI-verify recipe with
+an isolated `NOTA_DATA_DIR`) and open Help → What's New:
+
+- summary first, then a divider + "All changes", groups as section labels with bullets,
+ then Contributors — all expanded;
+- hover a commit hash: hand cursor + underline; click: the commit page opens in the
+ browser;
+- versions with old-format notes look as before.
+
+Capture a screenshot of the new layout for the PR.
diff --git a/specs/037-release-notes-full-list/research.md b/specs/037-release-notes-full-list/research.md
new file mode 100644
index 00000000..cce73237
--- /dev/null
+++ b/specs/037-release-notes-full-list/research.md
@@ -0,0 +1,117 @@
+# Research: Release notes with a full change list, commit links and contributors
+
+## R1. Marking the parts of the notes
+
+**Decision**: Two HTML-comment markers split the notes file into its parts, in this order:
+
+```
+<!-- SPDX-License-Identifier: AGPL-3.0-only -->
+lede + **N. Title** sections ← summary (unchanged format)
+<!-- changes -->
+**Added** / **Changed** / **Fixed** / **Removed** + • bullets ← full list
+<!-- contributors -->
+**Contributors** + one line of links ← contributors
+```
+
+Group titles are free text in the file's language («**Добавлено**» in RU); the markers, not
+the titles, say what a part is. Old files have no markers and parse as today.
+
+**Rationale**: language-independent — `release-notes.sh` must cut the full list out of the
+RU post as well as the EN one, and the app parser only sees EN. Comments are invisible on
+GitHub and in Telegram once stripped, and the parser already skips `<!--` lines.
+
+**Alternatives considered**: recognising group titles by name (needs an EN + RU word list
+in two places, breaks on a reworded title); a `---` rule (renders as a visible line on
+GitHub, and the github target already uses `---` before the install table).
+
+## R2. Item and contributor syntax
+
+**Decision**:
+
+- Item: `• Text of the change ([a1b2c3d](https://github.com/nota-daw/nota/commit/<full sha>))`;
+ several commits: `([a1b2c3d](…), [e4f5a6b](…))`. Link text = 7-char short hash, URL =
+ full sha.
+- Contributors: one line, `[@login](https://github.com/login)` joined with `, `. An author
+ without a GitHub account: plain name, no link.
+
+**Rationale**: the existing inline-Markdown renderer already handles `[text](url)`; GitHub
+and Telegram render the same text. One line keeps the post short.
+
+**Alternatives considered**: PR links (`#281`) — the user asked for commits; one bullet per
+contributor — long for 5+ people.
+
+## R3. The release range
+
+**Decision**: previous tag = highest `v*` tag by version
+(`git tag --list 'v*' --sort=-v:refname | head -1`), range `<prev-tag>..origin/develop`.
+
+**Rationale**: release tags sit on `main`'s merge commits, which `develop` never contains,
+so `git describe` on `develop` returns a stale tag (today: `v0.50.1` instead of
+`v0.56.1`). `git log v0.56.1..develop` correctly excludes everything merged into that tag
+(23 commits today). This also fixes the skill's existing P4 step 1.
+
+The squash commits on `develop` become ancestors of `main` through the develop → main merge
+commit, so their shas — and the links — stay valid after the release.
+
+## R4. Contributors and co-authors
+
+**Decision**: a new script `scripts/release-credits.sh <from> <to> <commits|contributors>`:
+
+- `commits` — one line per commit in the range, `<short> <full sha> <subject>`, oldest
+ first: the checklist the skill walks while writing the full list.
+- `contributors` — the ready Contributors line. For every commit it asks GitHub's GraphQL
+ API for `Commit.authors` (author **and** `Co-authored-by` trailers, each with
+ `user.login` when the email maps to an account), deduplicates by login, drops bots
+ (`[bot]` logins) and AI co-authors (`[email protected]`, login `claude`), sorts by
+ number of commits then name, and prints names without a login on stderr as a warning to
+ resolve by hand.
+
+**Rationale**: tested on `301d83c`: GraphQL returns the author with login, Claude as
+co-author, and a second email of the same person with `user: null` — exactly the cases the
+script must handle. REST `compare` gives only the primary author. `gh` is already required
+by the release flow (`release-verify.sh`).
+
+**Alternatives considered**: parsing `git log` emails (no logins; noreply addresses only for
+some people); REST per commit + search by email (rate-limited, private emails miss).
+
+## R5. News posts
+
+**Decision**: `release-notes.sh post-en|post-ru` drop the lines from `<!-- changes -->` up
+to `<!-- contributors -->`; the contributors part stays, then the download link. `github`
+keeps everything. All targets strip every `<!-- … -->` line (today only the SPDX one).
+
+**Rationale**: clarification 2026-10-22 (summary + contributors in posts). `release-verify.sh`
+compares against the same render, so it needs no change.
+
+## R6. Clickable links in What's New
+
+**Decision**: keep links as accent-coloured `Run`s inside the wrapping `TextBlock`, record
+each link's character range and URL while building the inlines, and on `PointerPressed`
+hit-test the point (`TextBlock.TextLayout.HitTestPoint`) to find the link; open it with
+`TopLevel.Launcher.LaunchUriAsync` (as `AppUpdates.OpenReleasePage` does). On
+`PointerMoved` over a link the cursor turns into a hand; links get an underline on hover.
+
+**Rationale**: text keeps wrapping naturally across the link; no new control per link;
+the same path makes every link in old notes clickable too (FR-008). Only `http(s)` URLs
+open.
+
+**Alternatives considered**: `InlineUIContainer` + `HyperlinkButton` per link — a link
+can't wrap mid-text and the button's padding breaks the baseline; a separate links row
+under each bullet — clutters a 396 px column.
+
+## R7. What's New layout for the new parts
+
+**Decision**: `ChangelogSection` gains a `Kind` (`Feature`, `Changes`, `Contributors`);
+`ReleaseNotesParser` sets it from the markers (sections before any marker keep today's
+behaviour: `Feature`). The window renders:
+
+- `Feature` — as today (13 px semibold title, paragraph, bullets);
+- `Changes` — the first one gets a thin divider and an "All changes" heading (the features' title style) above it;
+ each group uses the `SectionLabel` style (as the changelog fallback does) with bullets;
+- `Contributors` — `SectionLabel` "Contributors" and the line as a wrapped paragraph.
+
+Everything expanded (clarification 2026-10-22). Old notes and changelog fallbacks render
+exactly as today.
+
+**Rationale**: reuses the window's two existing heading styles, so the summary keeps its
+"release notes" look and the full list looks like the familiar changelog list.
diff --git a/specs/037-release-notes-full-list/spec.md b/specs/037-release-notes-full-list/spec.md
new file mode 100644
index 00000000..0f8f2e1c
--- /dev/null
+++ b/specs/037-release-notes-full-list/spec.md
@@ -0,0 +1,236 @@
+# Feature Specification: Release notes with a full change list, commit links and contributors
+
+**Feature Branch**: `feat/release-notes-full-list`
+
+**Created**: 2026-10-22
+
+**Status**: Draft (clarified 2026-10-22)
+
+**Input**: User description: "Update the release skill so the release texts have this structure: first, as before, an introduction of the release listing the main work done (a summary); then the full list of all work done — Added, Changed, Fixed; each item ends with a link to its commit; at the bottom, the contributors who took part in the release, linked to them. The What's New window must support this layout."
+
+## Nota Context *(fill in — drives plan and tasks)*
+
+**Feature area** *(pick the main one)*:
+
+- [ ] Engine (C++, `src/native/nota.engine`) — real-time audio rules apply, see `ARCHITECTURE.md` AR table
+- [x] Managed app (C#, `src/managed/*`) — domain, application, infrastructure, presentation
+- [ ] UI (Avalonia, `src/managed/Nota.Presentation`) — follow `DESIGN.md` (Studio)
+- [ ] Plugin hosting (`pluginhost/`) — the only place JUCE is allowed
+- [x] Build / packaging / CI (`scripts/`, `.github/`) — see `BUILD.md`
+- [ ] Docs only
+
+What exists today:
+
+- **Release skill** (`.claude/skills/release/SKILL.md` § P4) writes
+ `release-notes/X.Y.Z.en.md` and `X.Y.Z.ru.md`: a lede, numbered bold feature sections
+ (`**1. Title**` + a paragraph) and a final `**Also**` block of `•` bullets. No headings
+ (`#`), so the text pastes into Telegram as is. The full change history lives only in
+ `CHANGELOG.md`, which is never shown for a version that has curated notes.
+- **Rendering** (`scripts/release-notes.sh <version> github|post-en|post-ru`): the one
+ source of the published text — the GitHub release body (used by `release.yml`, checked
+ word for word by `scripts/release-verify.sh`) and the EN / RU news posts.
+- **What's New** (`src/managed/Nota.App/WhatsNewWindow.cs`, 460 px fixed, non-resizable):
+ for each unseen version shows the curated EN notes (bundled as
+ `Assets/ReleaseNotes/X.Y.Z.en.md`, parsed by `ReleaseNotesParser` in `Changelog.cs`) or
+ falls back to the version's `CHANGELOG.md` section. Inline Markdown supports bold,
+ italic, code and links — but a link shows only its text in accent colour and is not
+ clickable.
+- **Smoke test** (`tests/Nota.SmokeTest/ReleaseNotesTests.cs`) compiles `Changelog.cs`
+ directly, checks the parser against a sample and parses every shipped
+ `release-notes/*.en.md`.
+- **History**: the repo squash-merges PRs into `develop`, so one commit ≈ one PR; commit
+ subjects follow `(feat|fix|chore|ci) Subject (#NNN)`. Authors include outside
+ contributors (e.g. GitHub `noreply` addresses), so a commit author maps to a GitHub
+ account.
+
+No engine change.
+
+**Nota docs to keep in mind** *(links relative to `specs/<slug>/`, where this file lands)*:
+[`ARCHITECTURE.md`](../../ARCHITECTURE.md) (AR rules),
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md) (licensing, dependency policy, PR
+expectations), [`BUILD.md`](../../BUILD.md), [`DESIGN.md`](../../DESIGN.md),
+[`FEATURES.md`](../../FEATURES.md).
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - The release text has a summary, the full list and the people behind it (Priority: P1)
+
+The maintainer runs `/release prepare`. Next to the familiar summary (lede + numbered
+headline features), the curated notes now carry the complete list of what the release
+changed, grouped as **Added**, **Changed** and **Fixed**, each item ending with a link to
+the commit that brought it, and a closing **Contributors** line naming everyone who took
+part, each linked to their GitHub profile. The GitHub release body shows exactly this.
+
+**Why this priority**: it is the request itself — users and contributors see everything
+that shipped and who made it, and the commit links make each line traceable.
+
+**Independent Test**: prepare notes for a version, render the GitHub target, and check
+the four parts appear in order, every full-list item ends in a commit link that opens on
+GitHub, and every contributor links to their profile.
+
+**Acceptance Scenarios**:
+
+1. **Given** a release range with feature, fix and chore commits from two authors, **When**
+ the skill writes the notes, **Then** they contain the summary, then Added / Changed /
+ Fixed groups (empty groups omitted), then Contributors listing both authors.
+2. **Given** a user-visible change, **When** it appears in the full list, **Then** its line
+ ends with a link to the commit on `github.com/nota-daw/nota` showing the short hash.
+3. **Given** a purely internal commit (CI, refactor, tests), **When** the full list is
+ written, **Then** it is left out of the list, but its author still counts as a
+ contributor.
+4. **Given** the RU notes, **When** they are written, **Then** they have the same structure
+ and links, with group titles and items written natively in Russian.
+
+---
+
+### User Story 2 - What's New shows the new structure (Priority: P1)
+
+After updating, a user opens What's New. They read the summary first, then the full
+Added / Changed / Fixed list with each item's commit link, then the contributors. Links
+open in the browser.
+
+**Why this priority**: the user explicitly asked for What's New support; without it the
+bundled notes would display wrongly in the app.
+
+**Independent Test**: bundle a notes file in the new format and open What's New: the
+summary, the three groups and the contributors render in order, readable in the 460 px
+window, and clicking a commit or contributor link opens it in the browser.
+
+**Acceptance Scenarios**:
+
+1. **Given** new-format notes, **When** What's New opens, **Then** the summary sections
+ show as today, followed by Added / Changed / Fixed group headings with bullets, followed
+ by the contributors.
+2. **Given** a bullet ending in a commit link, **When** the user clicks the link, **Then**
+ the commit page opens in the default browser.
+3. **Given** a long full list, **When** What's New opens, **Then** the full list is shown
+ expanded, in order after the summary (no folding); the window scrolls.
+
+---
+
+### User Story 3 - Older notes and news posts keep working (Priority: P2)
+
+Notes written before this change (summary + **Also**) still display correctly in What's
+New, and the release tooling keeps producing valid GitHub and news-channel texts.
+
+**Why this priority**: shipped versions bundle old-format notes; a regression there shows
+broken text to every user who upgrades across several versions.
+
+**Independent Test**: the smoke test parses every shipped `release-notes/*.en.md`
+(old format) and a new-format sample; What's New shows a mix of both versions correctly.
+
+**Acceptance Scenarios**:
+
+1. **Given** a 0.56.1-style file, **When** parsed, **Then** it yields the same lede and
+ sections as before this change.
+2. **Given** a news post render (`post-en` / `post-ru`), **When** produced, **Then** its
+ it carries the summary and the contributors line but not the full list; the release
+ link at the bottom leads to the GitHub release with the full list.
+
+### Edge Cases
+
+- A change landed in several commits (a fix and its follow-up): one item, links to each
+ commit separated by commas.
+- A commit with several authors (`Co-authored-by:` trailers): every co-author is a
+ contributor.
+- An author whose commit email doesn't map to a GitHub account: listed by name without a
+ link, and the skill flags it to the maintainer.
+- Bots (e.g. dependabot) are not listed as contributors.
+- A patch release with only fixes: summary + **Fixed** + **Contributors**.
+- A release with no headline feature: lede alone, then the full list.
+- The **Also** block is replaced by the full list in new notes (no double listing).
+- Group titles in RU notes (e.g. «Добавлено», «Изменено», «Исправлено», «Участники») — the
+ app bundles only EN, so What's New must recognise the EN titles; RU titles only need to
+ render on GitHub/Telegram.
+
+## Clarifications
+
+### Session 2026-10-22
+
+- Q: How does What's New show the full list? → A: Expanded in full after the summary, no
+ folding.
+- Q: What goes into the news-channel posts? → A: Summary + contributors only; the full
+ list stays on GitHub (and in What's New).
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: The release skill MUST define the curated notes format as four parts in
+ order: (1) summary — lede plus numbered headline sections, as today; (2) full list in
+ groups **Added**, **Changed**, **Fixed** (and **Removed** when something was removed),
+ empty groups omitted; (3) each full-list item ending with a link to its commit(s);
+ (4) **Contributors**.
+- **FR-002**: The full list MUST cover every user-facing change in the release range,
+ reconciled with the code as P4 already requires (merged duplicates, nothing added and
+ removed within the release), and MUST NOT include internal-only commits.
+- **FR-003**: A commit link MUST point to `https://github.com/nota-daw/nota/commit/<sha>`
+ and show the short hash as its text; the sha MUST be the commit as it exists on
+ `develop` (the squash commit), so the link resolves after release.
+- **FR-004**: Contributors MUST be every distinct human author and co-author of a commit
+ in the release range (including internal commits), each linked to
+ `https://github.com/<login>`, shown by GitHub login.
+- **FR-005**: The skill MUST give the maintainer a way to gather items, commits and
+ contributors for the range (commands to run), and MUST say how to resolve an author to a
+ GitHub login.
+- **FR-006**: The format MUST stay Telegram-pasteable: no `#` headings; group titles use
+ the same bold-line convention as today.
+- **FR-007**: What's New MUST render new-format notes as: summary, then each group with
+ its title and bullets, then the contributors, in the Studio style.
+- **FR-008**: Links in What's New (commit links, contributor links and any other link in
+ notes) MUST be clickable and open in the default browser.
+- **FR-009**: What's New MUST keep rendering old-format notes and changelog fallbacks
+ exactly as before.
+- **FR-010**: `scripts/release-notes.sh` MUST render the GitHub target with all four parts;
+ `release-verify.sh` keeps comparing the draft with it. The news-post targets
+ (`post-en`, `post-ru`) MUST carry the summary and the contributors but leave out the
+ full list (Telegram's 4096-character limit), pointing to the GitHub release for it.
+- **FR-011**: The smoke test MUST cover parsing of the new format (groups, commit-linked
+ items, contributors) and keep parsing all shipped notes.
+
+### Key Entities
+
+- **Curated notes**: one version's text per language — summary, change groups,
+ contributors.
+- **Change item**: one user-facing change — text plus one or more commit links.
+- **Change group**: Added / Changed / Fixed / Removed with its items.
+- **Contributor**: a GitHub login (name and profile link) of a person with a commit in the
+ release range.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 100 % of user-facing commits in a release range appear as items in the full
+ list, and 100 % of the items carry a commit link that opens a real commit page.
+- **SC-002**: Every human author in the release range appears once in Contributors.
+- **SC-003**: All shipped release notes (old format) still parse and display identically
+ in What's New.
+- **SC-004**: A user opening What's New sees the release summary first, the full list
+ right after it (expanded), and can reach any commit from the window in one click.
+- **SC-005**: The published GitHub release body matches the curated notes word for word
+ (release-verify passes).
+
+## Assumptions
+
+- Commit links use squash commits on `develop`; history is not rewritten after a release
+ so the links stay valid (`main` takes merge commits, keeping the same shas).
+- Contributor logins come from the GitHub API for each commit in the range (the `gh` CLI
+ is already used by the release flow); a commit's `noreply` email also yields the login.
+- The full list is curated by the skill (one item per user-facing change), not dumped
+ from commit subjects; CHANGELOG.md stays the raw log and is not rewritten.
+- Existing release notes (0.5x) are not rewritten into the new format.
+- What's New stays 460 px fixed width; links are rendered as accent text as today, now
+ clickable.
+- FEATURES.md / user docs are not affected beyond a CHANGELOG entry for the What's New
+ change.
+
+## Nota Compliance Checklist *(review before implementation; re-check in tasks.md)*
+
+- [x] Every new source file will carry the AGPL-3.0-only SPDX header (two lines, see CONTRIBUTING.md)
+- [x] No new dependency — or: license checked, AGPL-compatible, `LICENSES/third-party.md` row planned
+- [x] Audio-thread impact considered: no alloc / lock / I/O on the audio thread (AR-6), command queue for data in (AR-4), immutable snapshots for structural edits (AR-5) — n/a, UI and tooling only
+- [x] Managed/native crossings go through the pure C ABI in `nota_engine.h` only (AR-7); no JUCE outside `pluginhost/` — no crossing
+- [x] Smoke-test impact assessed: engine behaviour change → extend `tests/Nota.SmokeTest` — parser tests extended (FR-011)
+- [x] User-visible change → `CHANGELOG.md` `[Unreleased]` entry planned (and FEATURES.md / user docs via the nota-features / nota-docs skills when working with an agent that has them)
+- [x] UI change → follows `DESIGN.md` (Studio design language)
diff --git a/specs/037-release-notes-full-list/tasks.md b/specs/037-release-notes-full-list/tasks.md
new file mode 100644
index 00000000..9e0f9bc8
--- /dev/null
+++ b/specs/037-release-notes-full-list/tasks.md
@@ -0,0 +1,144 @@
+---
+
+description: "Tasks: release notes with a full change list, commit links and contributors"
+---
+
+# Tasks: Release notes with a full change list, commit links and contributors
+
+**Input**: Design documents from `specs/037-release-notes-full-list/`
+
+**Prerequisites**: [plan.md](plan.md), [spec.md](spec.md), [research.md](research.md),
+[data-model.md](data-model.md), [contracts/release-notes-format.md](contracts/release-notes-format.md),
+[quickstart.md](quickstart.md)
+
+**Tests**: requested by the spec (FR-011) — the smoke test's `--release-notes` section is
+extended; scripts are checked by running them on a real range.
+
+**Organization**: grouped by user story (US1 release text, US2 What's New, US3 old notes
+and news posts).
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: can run in parallel (different files, no dependencies)
+- **[Story]**: the user story the task belongs to
+
+---
+
+## Phase 1: Setup
+
+- [X] T001 Create the working branch `feat/release-notes-full-list` off an up-to-date `develop`, carrying the untracked `specs/037-release-notes-full-list/` along
+
+---
+
+## Phase 2: Foundational (shared format)
+
+**Purpose**: the parser model every other part reads — markers and section kinds.
+
+- [X] T002 In `src/managed/Nota.App/Changelog.cs` add `public enum SectionKind { Feature, Changes, Contributors }` and a trailing `SectionKind Kind = SectionKind.Feature` parameter to `ChangelogSection`; update the file's header comment to describe the four-part format and the `<!-- changes -->` / `<!-- contributors -->` markers (data-model.md § App model)
+- [X] T003 In `ReleaseNotesParser.Parse` (`src/managed/Nota.App/Changelog.cs`): before skipping a `<!--` line, recognise exactly `<!-- changes -->` and `<!-- contributors -->` (trimmed, case-insensitive) — flush the current section and switch the kind for every following section; in a `Contributors` section the non-bullet line goes to `Text`; sections before any marker stay `Feature`, so files without markers parse exactly as today. Contributors must never precede changes in a valid file — a `<!-- changes -->` after `<!-- contributors -->` is ignored
+- [X] T004 Extend `tests/Nota.SmokeTest/ReleaseNotesTests.cs` with a new-format sample (contract §1): lede + 2 feature sections → `Feature`; `**Added**`, `**Fixed**` → `Changes` with their bullets, an item ending in `([a1b2c3d](https://github.com/nota-daw/nota/commit/…))` kept verbatim; `**Contributors**` → `Contributors` with the link line as `Text`; the marker lines don't leak into lede, text or items; keep the existing old-format sample assertions unchanged (they also prove `Kind == Feature`)
+
+**Checkpoint**: `dotnet run --project tests/Nota.SmokeTest -- --release-notes` green.
+
+---
+
+## Phase 3: User Story 1 — the release text has summary, full list, contributors (P1) 🎯 MVP
+
+**Goal**: `/release prepare` writes notes in the four-part format with commit links and
+linked contributors; the GitHub body shows all of it.
+
+**Independent Test**: quickstart §1 and §2 (`github` target) on the `v0.56.1..origin/develop` range.
+
+- [X] T005 [P] [US1] Create `scripts/release-credits.sh` (SPDX header, `set -euo pipefail`, usage line) per contract §3: `commits` prints `git log --reverse --format='%h%x09%H%x09%s' <from>..<to>`, no network; `contributors` checks `gh` and `jq`, for each sha in the range queries `gh api graphql` for `repository(owner:"nota-daw",name:"nota"){object(oid:$oid){... on Commit{authors(first:20){nodes{name email user{login}}}}}}` (batch several shas per query with aliases if simple), fails with a clear message when a commit is not on GitHub, drops logins ending in `[bot]`, login `claude` and email `[email protected]`, counts commits per login, prints one line `[@login](https://github.com/login)` joined by `, ` (most commits first, ties by login), and for authors with `user: null` prints `warn: no GitHub login for <name> <email>` to stderr and appends the plain name only if its email/name doesn't belong to a listed login's other commits; `chmod +x`
+- [X] T006 [P] [US1] In `scripts/release-notes.sh` change `body()` to drop every line matching `^<!--.*-->$` (not only the SPDX one) so the markers never reach any output; `github` keeps all parts; update the header comment to name the four parts
+- [X] T007 [US1] Rewrite `.claude/skills/release/SKILL.md` § P4: step 1 *Gather* takes the previous tag by version (`git tag --list 'v*' --sort=-v:refname | head -1`, explain why `git describe` on develop is wrong — research R3) and runs `scripts/release-credits.sh <prev-tag> origin/develop commits` / `contributors`; step 2 *Reconcile* also builds the full list (every user-facing change of the range, one item per change, each with its commit link(s), internal commits left out but their authors kept); step 3 *Write* shows the full four-part format from contract §1 with both markers, the group order Added / Changed / Fixed / Removed (empty omitted), RU titles (Добавлено, Изменено, Исправлено, Удалено, Участники), the item syntax `• text ([short](https://github.com/nota-daw/nota/commit/<sha>))`, the contributors line, "no **Also** in new notes — the full list replaces it", and that EN and RU share groups, order, links and contributors; step 4 says the posts carry summary + contributors and the GitHub body everything (show `github` too). Update the intro table of targets and the "Don't" list (don't hand-edit contributors; resolve every `warn:` line)
+- [X] T008 [US1] Also in `.claude/skills/release/SKILL.md`: fix the release poster step / P8 wording if it references "Also"; mention in P8 that the develop → main PR body (`github` output) now includes the full list
+
+**Checkpoint**: quickstart §1 lists the range's commits and the contributors (≥ `ambertape`, `rafi612`, no `claude`); a sample rendered with `github` shows all four parts and no `<!--` lines.
+
+---
+
+## Phase 4: User Story 2 — What's New shows the new structure (P1)
+
+**Goal**: the window renders summary → "All changes" groups → contributors, all expanded,
+with clickable links.
+
+**Independent Test**: quickstart §4 with the 9.9.9 sample in the headless harness / real app.
+
+- [X] T009 [US2] In `src/managed/Nota.App/WhatsNewWindow.cs` `EntryBlock`: for release notes render sections by `Kind` — `Feature` as today; before the first `Changes` section add a 1 px divider (`Brush.Border`-style seam token per DESIGN.md) and an "All changes" heading in the features' title style; each `Changes` section uses the `SectionLabel` title style (as the changelog fallback) with its bullets; a `Contributors` section uses `SectionLabel` + `Paragraph(section.Text, "Brush.TextSecondary")`; everything expanded; changelog-fallback entries unchanged
+- [X] T010 [US2] In `AppendInlineMarkdown` (`src/managed/Nota.App/WhatsNewWindow.cs`) record for each `[label](url)` the character range of its run in the block's text and the URL (keep a per-block list, e.g. attached via a private field/dictionary keyed by the `TextBlock`); on the block's `PointerPressed` hit-test the point with `block.TextLayout.HitTestPoint(...)`, and if the position falls inside a link range with an `http`/`https` URL open it via `TopLevel.GetTopLevel(this)?.Launcher.LaunchUriAsync(new Uri(url))` and mark the event handled; on `PointerMoved` set a hand cursor and underline (`TextDecorations.Underline`) the hovered link's run, reset on leave. Applies to every link in old notes too (FR-008)
+- [X] T011 [US2] Verify with the UI-verify recipe (isolated `NOTA_DATA_DIR`, headless Avalonia render or the real app): a temporary 9.9.9 EN sample shows the new layout within the 396 px column without clipping; hovering a hash shows the hand cursor; clicking opens the commit URL; capture a screenshot for the PR (outside the repo, `/tmp`); remove the temporary sample afterwards
+
+**Checkpoint**: the new layout renders; old versions look as before.
+
+---
+
+## Phase 5: User Story 3 — old notes and news posts keep working (P2)
+
+**Goal**: shipped notes display unchanged; posts omit the full list.
+
+**Independent Test**: quickstart §2 (`post-ru`, old `0.56.1 github` byte-identical) and §3.
+
+- [X] T012 [P] [US3] In `scripts/release-notes.sh` for `post-en` / `post-ru` drop the lines from `<!-- changes -->` up to (not including) `<!-- contributors -->` before stripping comments, then collapse runs of blank lines; files without markers render as today
+- [X] T013 [US3] Check that `scripts/release-notes.sh 0.56.1 github`, `post-en`, `post-ru` are byte-identical before and after the change (save outputs from `origin/develop` first with `git stash`/a temp worktree, diff after)
+- [X] T014 [P] [US3] In `tests/Nota.SmokeTest/ReleaseNotesTests.cs` add: for every shipped `release-notes/*.en.md`, a file that contains `<!-- changes -->` must also contain `<!-- contributors -->` after it, have at least one `Changes` section, and every `Changes` bullet must end with a commit link matching `\(\[[0-9a-f]{7}\]\(https://github\.com/nota-daw/nota/commit/[0-9a-f]{40}\)(, \[[0-9a-f]{7}\]\(https://github\.com/nota-daw/nota/commit/[0-9a-f]{40}\))*\)$`; files without markers only need today's checks
+
+**Checkpoint**: smoke test green, old renders identical.
+
+---
+
+## Phase 6: Polish & Cross-Cutting
+
+- [X] T015 Run quickstart.md §1–§4 end to end and note results
+- [X] T016 [P] Update the header comments of `src/managed/Nota.App/WhatsNewWindow.cs` and `tests/Nota.SmokeTest/ReleaseNotesTests.cs` to mention the full list, contributors and clickable links
+
+### Nota closing tasks *(PR gates)*
+
+- [X] T017 Run `scripts/build.sh` until native + managed + smoke test are green
+- [X] T018 AGPL-3.0-only SPDX header on `scripts/release-credits.sh` (the only new file)
+- [X] T019 New dependency: N/A (`gh`, `jq` already used by `release-verify.sh`)
+- [X] T020 `CHANGELOG.md` `[Unreleased]` → Changed: What's New shows each release's full list of changes with commit links and its contributors; links in What's New open in the browser
+- [X] T021 `nota-features`: update FEATURES.md if it describes What's New / release notes; `nota-docs`: check the What's New mention in the user docs; `nota-shortcuts`: N/A
+- [X] T022 Engine behaviour change: N/A (parser tests extended in T004, T014)
+
+---
+
+## Dependencies & Execution Order
+
+- **Setup (T001)** → **Foundational (T002–T004)** → stories.
+- **US1** (T005–T008): T005, T006 parallel; T007–T008 after them (the skill names the scripts' interfaces). Doesn't need US2.
+- **US2** (T009–T011): needs T002–T003; independent of US1's scripts.
+- **US3** (T012–T014): T012 touches `release-notes.sh` after T006 (same file); T014 after T004.
+- **Polish** after all stories.
+
+### Parallel Opportunities
+
+- T005 ∥ T006 ∥ T009 (different files) once the foundation is in.
+- T014 ∥ T012 (test file vs. script).
+
+## Parallel Example: User Story 1
+
+```bash
+Task: "Create scripts/release-credits.sh (commits | contributors)"
+Task: "release-notes.sh: strip every comment line in body()"
+```
+
+## Implementation Strategy
+
+1. T001–T004: the format and parser, proven by the smoke test.
+2. US1 (MVP): the release produces the new text — usable right away for the next release
+ on GitHub.
+3. US2: What's New displays it; ship together with US1 so the next release's bundled notes
+ render correctly.
+4. US3: guard the old notes and the post format.
+5. Closing gates, then `/speckit-converge`.
+
+## Notes
+
+- One PR for the whole feature; the user commits and pushes (no commits by the agent).
+- Old `release-notes/0.5x.*` files are not rewritten.
+
+## Phase 7: Convergence
+
+- [X] T023 Make `scripts/release-credits.sh contributors` fail when GitHub lacks a commit: for an unknown sha `gh api graphql … --jq '… .value'` prints an empty line, not `null`, so the `grep -qx 'null'` check never fires and that commit's authors are silently dropped — emit each answer as compact JSON (e.g. `--jq '.data.repository | to_entries[] | (.value // {missing: true}) | tojson'` or count non-null answers with `oid`), compare with the number of shas queried, and exit 1 with "some commits … aren't on GitHub yet — push them first"; check with a range ending in a local unpushed commit per FR-004, contract §3 (partial)
+- [X] T024 Match the part markers one way everywhere — trimmed, case-insensitive, whitespace inside the comment tolerated (`<!--\s*changes\s*-->`): `ReleaseNotesParser` in `src/managed/Nota.App/Changelog.cs` (a shared static `Regex` per marker instead of `Equals`), the awk patterns in `scripts/release-notes.sh` (`tolower($0)`), and the shipped-file check in `tests/Nota.SmokeTest/ReleaseNotesTests.cs` (use the parser's regexes instead of `IndexOf(..., Ordinal)`) per data-model: Curated notes file, T003/T012/T014 (partial)
diff --git a/src/managed/Nota.App/Changelog.cs b/src/managed/Nota.App/Changelog.cs
index 27e0805f..54ed4ccf 100644
--- a/src/managed/Nota.App/Changelog.cs
+++ b/src/managed/Nota.App/Changelog.cs
@@ -9,9 +9,13 @@
// AppInfo.UnseenSince skips it — unreleased notes never reach the What's New window.
//
// ReleaseNotesParser reads the curated notes a release ships (release-notes/X.Y.Z.en.md,
-// format in .claude/skills/release/SKILL.md § P4): a lede, "**N. Title**" sections with
-// a paragraph each, and "**Also**" with "•" bullets. What's New prefers them over the
-// raw changelog section. No Avalonia here: the smoke test compiles this file directly.
+// format in .claude/skills/release/SKILL.md § P4): a summary — a lede and "**N. Title**"
+// sections with a paragraph each — then, after a "<!-- changes -->" marker, the full
+// list as "**Added**" / "**Changed**" / "**Fixed**" groups of "•" bullets ending in commit
+// links, and after "<!-- contributors -->" a "**Contributors**" line of profile links.
+// Notes from before the markers (a summary and "**Also**" bullets) parse as all-Feature
+// sections. What's New prefers the notes over the raw changelog section. No Avalonia
+// here: the smoke test compiles this file directly.
using System;
using System.Collections.Generic;
@@ -29,9 +33,15 @@ public sealed record ChangelogEntry(string Version, string Date,
}
/// <summary>A category within a changelog entry (Added / Changed / Fixed / Removed), or a
-/// feature of curated release notes: its title, a paragraph (<see cref="Text"/>) and/or
-/// bullets.</summary>
-public sealed record ChangelogSection(string Title, IReadOnlyList<string> Items, string Text = "");
+/// part of curated release notes: its title, a paragraph (<see cref="Text"/>) and/or
+/// bullets. <see cref="Kind"/> says which part of the notes it belongs to.</summary>
+public sealed record ChangelogSection(string Title, IReadOnlyList<string> Items, string Text = "",
+ SectionKind Kind = SectionKind.Feature);
+
+/// <summary>Which part of curated release notes a section is in: the summary's features
+/// (and every changelog category), a group of the full change list, or the
+/// contributors.</summary>
+public enum SectionKind { Feature, Changes, Contributors }
/// <summary>A comparable semantic version (MAJOR.MINOR.PATCH). Pre-release/build
/// metadata is ignored — the app only ships plain X.Y.Z versions.</summary>
@@ -149,6 +159,13 @@ public static class ReleaseNotesParser
// order in a news post; the window keeps the order and drops the number.
private static readonly Regex Heading = new(@"^\*\*(?:\d+\.\s*)?(?<title>(?:(?!\*\*).)+)\*\*$");
+ // Where the full change list and the contributors start: "<!-- changes -->" and
+ // "<!-- contributors -->" alone on a (trimmed) line, any case, any spacing inside.
+ // Comments, so they vanish on GitHub and in the posts whatever the language;
+ // release-notes.sh and the smoke test match them the same way.
+ public static readonly Regex ChangesMarker = new(@"^<!--\s*changes\s*-->$", RegexOptions.IgnoreCase);
+ public static readonly Regex ContributorsMarker = new(@"^<!--\s*contributors\s*-->$", RegexOptions.IgnoreCase);
+
public static ChangelogEntry Parse(string version, string date, string markdown)
{
var lede = new List<string>();
@@ -156,11 +173,12 @@ public static class ReleaseNotesParser
string? title = null;
var text = new List<string>();
var items = new List<string>();
+ var kind = SectionKind.Feature;
void FlushSection()
{
if (title != null && (text.Count > 0 || items.Count > 0))
- sections.Add(new ChangelogSection(title, items.ToArray(), string.Join("\n", text)));
+ sections.Add(new ChangelogSection(title, items.ToArray(), string.Join("\n", text), kind));
title = null;
text.Clear();
items.Clear();
@@ -169,7 +187,23 @@ public static class ReleaseNotesParser
foreach (var raw in markdown.Split('\n'))
{
var t = raw.Trim();
- if (t.Length == 0 || t.StartsWith("<!--", StringComparison.Ordinal)) continue;
+ if (t.Length == 0) continue;
+ if (t.StartsWith("<!--", StringComparison.Ordinal))
+ {
+ // The part markers; contributors close the notes, so a later
+ // "changes" marker can't reopen the list.
+ if (ChangesMarker.IsMatch(t) && kind == SectionKind.Feature)
+ {
+ FlushSection();
+ kind = SectionKind.Changes;
+ }
+ else if (ContributorsMarker.IsMatch(t))
+ {
+ FlushSection();
+ kind = SectionKind.Contributors;
+ }
+ continue;
+ }
if (Heading.Match(t) is { Success: true } m)
{
diff --git a/src/managed/Nota.App/WhatsNewWindow.cs b/src/managed/Nota.App/WhatsNewWindow.cs
index 3883f98c..164c2882 100644
--- a/src/managed/Nota.App/WhatsNewWindow.cs
+++ b/src/managed/Nota.App/WhatsNewWindow.cs
@@ -4,7 +4,10 @@
// "What's new" — shown once after the first launch on a newer app version (see
// MainWindow.OnOpenedWhatsNew). Lists the versions the user hasn't seen yet, newest
// first: a release's curated notes (the GitHub release text) where it has them,
-// otherwise its changelog section. Reachable any time from the Help menu too.
+// otherwise its changelog section. Curated notes show their summary, then "All changes"
+// (the Added / Changed / Fixed groups, each item with its commit link), then the
+// contributors, all expanded. Links open in the browser. Reachable any time from the
+// Help menu too.
using System;
using System.Collections.Generic;
@@ -12,6 +15,7 @@ using System.Text;
using Avalonia;
using Avalonia.Controls;
using Avalonia.Controls.Documents;
+using Avalonia.Input;
using Avalonia.Layout;
using Avalonia.Media;
@@ -108,17 +112,26 @@ public sealed class WhatsNewWindow : NotaWindow
if (entry.IsReleaseNotes)
panel.Children.Add(Paragraph(entry.Lede, "Brush.TextPrimary"));
+ bool listStarted = false;
foreach (var section in entry.Sections)
{
- panel.Children.Add(entry.IsReleaseNotes
- ? new TextBlock
+ // The summary's features read as headings; the full list and the
+ // contributors use the changelog's quieter group labels under one
+ // "All changes" heading, after a seam.
+ bool feature = entry.IsReleaseNotes && section.Kind == SectionKind.Feature;
+ if (entry.IsReleaseNotes && section.Kind == SectionKind.Changes && !listStarted)
+ {
+ listStarted = true;
+ panel.Children.Add(new Border
{
- Text = section.Title,
- FontSize = 13,
- FontWeight = FontWeight.SemiBold,
- Foreground = Brush("Brush.TextPrimary"),
- Margin = new Thickness(0, 6, 0, 0),
- }
+ Height = 1,
+ Background = Brush("Brush.BorderDefault"),
+ Margin = new Thickness(0, 10, 0, 2),
+ });
+ panel.Children.Add(FeatureTitle("All changes"));
+ }
+ panel.Children.Add(feature
+ ? FeatureTitle(section.Title)
: new TextBlock
{
Classes = { "SectionLabel" },
@@ -133,6 +146,15 @@ public sealed class WhatsNewWindow : NotaWindow
return panel;
}
+ private TextBlock FeatureTitle(string text) => new()
+ {
+ Text = text,
+ FontSize = 13,
+ FontWeight = FontWeight.SemiBold,
+ Foreground = Brush("Brush.TextPrimary"),
+ Margin = new Thickness(0, 6, 0, 0),
+ };
+
private Control Paragraph(string text, string brush)
{
var block = new TextBlock
@@ -167,13 +189,16 @@ public sealed class WhatsNewWindow : NotaWindow
}
// Renders the inline Markdown the changelog and release notes use: **bold**, *italic*,
- // `code` and [links](url) (link text only). Underscores are left alone —
- // they show up inside identifiers like `get_rhythm_macros`.
+ // `code` and [links](url) — the link text in accent colour, clickable (see
+ // AttachLinks). Underscores are left alone — they show up inside identifiers like
+ // `get_rhythm_macros`.
private void AppendInlineMarkdown(TextBlock block, string text)
{
var inlines = block.Inlines ??= new InlineCollection();
var buf = new StringBuilder();
bool bold = false, italic = false;
+ int pos = 0; // characters laid out so far — where the next run starts
+ var links = new List<Link>();
void Flush()
{
@@ -186,6 +211,7 @@ public sealed class WhatsNewWindow : NotaWindow
}
if (italic) run.FontStyle = FontStyle.Italic;
inlines.Add(run);
+ pos += buf.Length;
buf.Clear();
}
@@ -203,6 +229,7 @@ public sealed class WhatsNewWindow : NotaWindow
if (this.TryFindResource("Font.Mono", out var mono) && mono is FontFamily ff)
code.FontFamily = ff;
inlines.Add(code);
+ pos += end - i - 1;
i = end;
}
else if (c == '*' && i + 1 < text.Length && text[i + 1] == '*'
@@ -221,22 +248,67 @@ public sealed class WhatsNewWindow : NotaWindow
&& text.IndexOf(')', mid + 2) is var close and > 0)
{
Flush();
- AppendLinkText(text[(i + 1)..mid]);
+ AppendLink(text[(i + 1)..mid], text[(mid + 2)..close]);
i = close;
}
else buf.Append(c);
}
Flush();
+ if (links.Count > 0) AttachLinks(block, links);
- void AppendLinkText(string label)
+ void AppendLink(string label, string url)
{
- buf.Append(label);
- var run = new Run(buf.ToString()) { Foreground = Brush("Brush.Accent") };
+ var run = new Run(label) { Foreground = Brush("Brush.Accent") };
if (bold) run.FontWeight = FontWeight.SemiBold;
if (italic) run.FontStyle = FontStyle.Italic;
inlines.Add(run);
- buf.Clear();
+ if (Uri.TryCreate(url.Trim(), UriKind.Absolute, out var uri)
+ && (uri.Scheme == Uri.UriSchemeHttps || uri.Scheme == Uri.UriSchemeHttp))
+ links.Add(new Link(pos, label.Length, uri, run));
+ pos += label.Length;
+ }
+ }
+
+ private sealed record Link(int Start, int Length, Uri Uri, Run Run);
+
+ // A Run can't take pointer input, so the block hit-tests the pointer against its
+ // laid-out text and finds the link under it: hand cursor and underline on hover,
+ // a click opens the URL in the default browser. The text keeps wrapping through
+ // the link as ordinary text.
+ private void AttachLinks(TextBlock block, List<Link> links)
+ {
+ Link? hovered = null;
+
+ Link? At(PointerEventArgs e)
+ {
+ // HitTestPoint snaps to the nearest character even past a line's end, so
+ // check the pointer is over that character's box (a click right of a line
+ // that ends in a link must not open it).
+ var p = e.GetPosition(block);
+ int at = block.TextLayout.HitTestPoint(p).TextPosition;
+ var link = links.Find(l => at >= l.Start && at < l.Start + l.Length);
+ if (link == null) return null;
+ var box = block.TextLayout.HitTestTextPosition(at);
+ return p.Y >= box.Top && p.Y < box.Bottom && p.X >= box.Left - 1 && p.X <= box.Right + 1 ? link : null;
+ }
+
+ void Hover(Link? link)
+ {
+ if (ReferenceEquals(link, hovered)) return;
+ if (hovered != null) hovered.Run.TextDecorations = null;
+ hovered = link;
+ if (link != null) link.Run.TextDecorations = TextDecorations.Underline;
+ block.Cursor = link != null ? new Cursor(StandardCursorType.Hand) : null;
}
+
+ block.PointerMoved += (_, e) => Hover(At(e));
+ block.PointerExited += (_, _) => Hover(null);
+ block.PointerPressed += (_, e) =>
+ {
+ if (!e.GetCurrentPoint(block).Properties.IsLeftButtonPressed || At(e) is not { } link) return;
+ _ = TopLevel.GetTopLevel(this)?.Launcher.LaunchUriAsync(link.Uri);
+ e.Handled = true;
+ };
}
private IBrush Brush(string key)
diff --git a/tests/Nota.SmokeTest/ReleaseNotesTests.cs b/tests/Nota.SmokeTest/ReleaseNotesTests.cs
index cce7b0ab..2e2e16f3 100644
--- a/tests/Nota.SmokeTest/ReleaseNotesTests.cs
+++ b/tests/Nota.SmokeTest/ReleaseNotesTests.cs
@@ -4,7 +4,8 @@
// What's New shows a release's curated notes (release-notes/X.Y.Z.en.md, the GitHub
// release text) instead of its raw CHANGELOG.md section. Every shipped notes file must
// parse into a lede and titled sections, and the parser must read the format the release
-// skill writes. Also runnable alone: `dotnet run --project tests/Nota.SmokeTest -- --release-notes`.
+// skill writes: a summary, the full change list after "<!-- changes -->" (every item ending
+// in a commit link) and the contributors after "<!-- contributors -->". Also runnable alone: `dotnet run --project tests/Nota.SmokeTest -- --release-notes`.
using Nota.App;
@@ -41,6 +42,45 @@ internal static class ReleaseNotesTests
"release notes: a feature's paragraph is its text");
yield return (e.Sections[2].Items.SequenceEqual(new[] { "a small fix with `code`", "**bold** start, plain end" }),
"release notes: \"•\" lines become bullets, and a bold-led bullet isn't a heading");
+ yield return (e.Sections.All(s => s.Kind == SectionKind.Feature),
+ "release notes: notes without part markers are all summary sections");
+
+ const string link = "([a1b2c3d](https://github.com/nota-daw/nota/commit/a1b2c3d4e5f60718293a4b5c6d7e8f9012345678))";
+ var full = $"""
+ <!-- SPDX-License-Identifier: AGPL-3.0-only -->
+ Nota 9.9 has a full list.
+
+ **1. First feature**
+ What it is.
+
+ <!-- changes -->
+ **Added**
+ • A new thing {link}
+
+ **Fixed**
+ • A fix {link}
+ • Another fix {link}
+
+ <!--Contributors -->
+ **Contributors**
+ [@ambertape](https://github.com/ambertape), [@rafi612](https://github.com/rafi612)
+ """;
+ var n = ReleaseNotesParser.Parse("9.9.2", "", full);
+ yield return (n.Lede == "Nota 9.9 has a full list."
+ && n.Sections.Select(s => (s.Title, s.Kind)).SequenceEqual(new[]
+ {
+ ("First feature", SectionKind.Feature),
+ ("Added", SectionKind.Changes),
+ ("Fixed", SectionKind.Changes),
+ ("Contributors", SectionKind.Contributors),
+ }),
+ $"release notes: the markers split summary, change groups and contributors ({string.Join(" | ", n.Sections.Select(s => $"{s.Title}:{s.Kind}"))})");
+ yield return (n.Sections[2].Items.SequenceEqual(new[] { $"A fix {link}", $"Another fix {link}" })
+ && n.Sections[0].Text == "What it is.",
+ "release notes: change items keep their commit links, no marker leaks into the text");
+ yield return (n.Sections[3].Items.Count == 0
+ && n.Sections[3].Text == "[@ambertape](https://github.com/ambertape), [@rafi612](https://github.com/rafi612)",
+ "release notes: the contributors line is the section's text");
var root = RepoRoot();
yield return (root is not null, "release notes: repo root found");
@@ -52,12 +92,28 @@ internal static class ReleaseNotesTests
foreach (var f in files)
{
var version = Path.GetFileName(f)[..^".en.md".Length];
- var notes = ReleaseNotesParser.Parse(version, "", File.ReadAllText(f));
+ var text = File.ReadAllText(f);
+ var notes = ReleaseNotesParser.Parse(version, "", text);
yield return (notes.IsReleaseNotes && notes.Sections.Count > 0
&& notes.Sections.All(s => s.Title.Length > 0 && (s.Text.Length > 0 || s.Items.Count > 0)),
$"release notes {version}: parses into a lede and {notes.Sections.Count} titled sections");
yield return (changelog.Any(c => c.Version == version),
$"release notes {version}: CHANGELOG.md has its section (What's New pairs them by version)");
+
+ // Notes with the full list: both markers in order, and every change item
+ // ends in its commit link(s).
+ var lines = text.Split('\n').Select(l => l.Trim()).ToList();
+ int changes = lines.FindIndex(l => ReleaseNotesParser.ChangesMarker.IsMatch(l));
+ if (changes < 0) continue;
+ int contributors = lines.FindIndex(l => ReleaseNotesParser.ContributorsMarker.IsMatch(l));
+ var unlinked = notes.Sections.Where(s => s.Kind == SectionKind.Changes)
+ .SelectMany(s => s.Items).Where(i => !CommitLinks.IsMatch(i)).ToList();
+ yield return (contributors > changes
+ && notes.Sections.Any(s => s.Kind == SectionKind.Changes)
+ && notes.Sections.Any(s => s.Kind == SectionKind.Contributors),
+ $"release notes {version}: the full list is followed by the contributors");
+ yield return (unlinked.Count == 0,
+ $"release notes {version}: every change ends in a commit link{(unlinked.Count > 0 ? " — missing: " + unlinked[0] : "")}");
}
var csproj = File.ReadAllText(Path.Combine(root, "src/managed/Nota.App/Nota.App.csproj"));
@@ -65,6 +121,11 @@ internal static class ReleaseNotesTests
"release notes: Nota.App embeds release-notes/*.en.md where AppInfo reads them");
}
+ // "… ([a1b2c3d](https://github.com/nota-daw/nota/commit/<40 hex>), […](…))" at the end.
+ private const string CommitLink = @"\[[0-9a-f]{7}\]\(https://github\.com/nota-daw/nota/commit/[0-9a-f]{40}\)";
+ private static readonly System.Text.RegularExpressions.Regex CommitLinks =
+ new($@"\({CommitLink}(, {CommitLink})*\)$");
+
private static string? RepoRoot()
{
var d = new DirectoryInfo(AppContext.BaseDirectory);