Prepare Release

Campfire release preparation

Produce one throwaway markdown file whose whole contents the user pastes into the description of a new GitHub release: the notes people read, followed by the hidden block publish-all.yml reads. Publishing that release is the entire release process, so the file has to be complete as it is — nothing to fill in, nothing to cut before pasting. Match the style of the existing notes at https://github.com/pandulapeter/campfire/releases.

Also update the tracked in-app message resources and regenerate the tracked Android profiles before the release is tagged. These are part of preparing every release, including a small release with empty notes.

Campfire is an app, not a library. The notes are for the people who use it — musicians — not for developers reading the source. Nothing about modules, classes, Gradle, Koin or the build belongs in them. If a change has no effect a user could notice, it is not in the notes.

Process

1. Determine the version. The release version is campfire.versionName in gradle.properties (campfire.buildNumber, which every platform shares, moves with it). The GitHub tag is that number without the v prefix (4.0.1), even though the bump commit spells it with one.

2. Find the previous release boundary — the last release tag, never a version bump commit (a bump can land for a version that was never published, and a release is what the tag marks):

   grep -n 'campfire.versionName' gradle.properties
   git fetch --tags origin
   gh release list --limit 3
   git describe --tags --abbrev=0 --match '[0-9]*.[0-9]*.[0-9]*' --exclude "$(sed -n 's/^campfire\.versionName=//p' gradle.properties)"
   git tag --list '[0-9]*.[0-9]*.[0-9]*' --sort=-v:refname | head -3

   The git describe line prints <last tag>: release tags are bare version numbers, so older v-prefixed tags (v1.0.0) are never a boundary, and the version being prepared is excluded so that a run after that version was already tagged (on HEAD or on a commit before it) still finds the release before it. The range is <last tag>..HEAD, for the GitHub notes, the stores' blurb and the in-app message alike: every change since the last published release is in scope, whatever else was prepared or reverted in between. Fetch the tags first: a release is published on GitHub, which creates its tag there and nowhere else, so a clone that has not fetched since misses the newest one and would put a release that already shipped into these notes. The <last tag> must be the newest non-pre-release that gh release list shows (other than the version being prepared); if the two disagree, stop and find out why before writing anything.

3. List the commits in the range and group them by feature. Many commits usually build one feature (a PDF export is dozens), so cluster them by the user-visible capability before judging importance:

   git log <last tag>..HEAD --format='%H %s'
   git diff <last tag>..HEAD --stat -- presentation domain data chordpro app | tail -40

   Do not stop at the strings diff: a feature that rebuilds an existing screen (a new reading layout, new ways to page through a song) adds few strings and is easy to miss. Check which screens and CLAUDE.md sections changed most, and read those diffs.

4. Read the actual diffs — never summarize from commit subjects. Subjects are lossy and often name the mechanism rather than the effect. For each commit:

   git show <hash>                                   # the change itself
   git show --name-only --format='' <hash>           # which areas it touched

   Pay particular attention to two files, because they say what a user will see:

   git diff <last tag>..HEAD -- presentation/src/commonMain/composeResources/values/strings.xml
   git diff <last tag>..HEAD --stat -- presentation domain data chordpro app

   New or changed strings are almost always a new feature, a new setting or a new message worth a bullet.

5. Judge every change against the last release tag, not against the previous commit. A user only knows what was in the last published release. A fix for a bug introduced after that tag, for a feature or dialog that did not exist in it, or for a rough edge of something still unreleased, is part of that new work and never gets a bullet of its own: the feature's bullet already describes it as it now is. Test each candidate fix by asking whether somebody running the last release could have hit the problem. Never pad the list with recent small commits; if no fix qualifies, there is no fixes bullet. The same goes for polish of new features (layout tweaks, accessibility labels, performance of code that is new): it belongs inside the feature's description or nowhere.

   Then sort what you found into user-facing and not. Keep: new features, new settings, changed behavior somebody relied on, fixed bugs a user could hit, visible design changes, new or improved platform support, new languages, performance a user can feel (loading, scrolling, sync speed). Drop: refactors, dependency bumps, Lint and warning cleanups, test changes, CI and build configuration, documentation and CLAUDE.md edits — unless the build change is itself the user-visible thing (a smaller download, a fixed release build, a new distributable).

6. Note which platforms each surviving change affects. Campfire ships four builds from one codebase, and a bullet that is only true on one of them has to say so ("on iOS", "on the web"). A change in commonMain is everywhere and needs no qualifier; a change under app/<platform> or in a <platform>Main source set usually needs one.

7. Always update the in-app message. Follow .claude/skills/code-style/SKILL.md before editing resources. Set whats_new_message in both:

   • presentation/src/commonMain/composeResources/values/strings.xml (English);
   • presentation/src/commonMain/composeResources/values-hu/strings.xml (Hungarian).

   Write the bullets by Writing the changelog below: at most six, each a bold headline and a one-sentence description, sorted by importance. Before writing, list the feature clusters from step 3, rank them, and check that the six (or fewer) that made it are the ones a user would miss most.

   Store each bullet on one line as • **Headline** Description (the literal • , the headline between ** pairs, then a space and the description), and separate bullets with \n in the XML string (for example, • **Print in up to four columns** Fit more of a song on each page.\n• **...** ...). The dialog draws the headline bold on its own line with the description under it, as spaced rows in a scrollable area with fades at the top and bottom; its title and Get started button stay visible. No other Markdown, links, emoji, introductory paragraph or version number in the body. Translate the same bullets into natural Hungarian and escape XML correctly. Keep whats_new_title as the localized title with its %1$s version placeholder. Replace the previous message rather than appending history. Empty notes are valid: when the user wants no notes for a very small release, or there is no user-facing change to announce, explicitly set <string name="whats_new_message"></string> in both files. Never leave the previous release's text behind. Blank or whitespace-only messages suppress the dialog; the app still records the version as handled. The first installed version is always skipped, whatever its message contains.

8. Always regenerate Android baseline profiles, and only once every other source change is in place — the in-app message and any code or resource edit made while preparing the release (step 7 included), since the profile is recorded from the built app and a later change would leave it stale. If anything under presentation, app or the shared modules changes after a recording, record it again. Follow app/baselineprofile/CLAUDE.md's recording procedure: use an English emulator (boot Resizable_Experimental if needed), wait for it to finish booting, and select it explicitly with ANDROID_SERIAL when several devices are connected. Uninstall com.pandulapeter.campfire only from that recording emulator if present, to start with a fresh library and avoid signing conflicts; never uninstall the .debug app or touch a user's physical device. Run:

   ./gradlew :app:android:generateBaselineProfile

   Verify that both baseline-prof.txt and startup-prof.txt in app/android/src/main/generated/baselineProfiles are nonempty and include app rules; the baseline profile must also contain androidx/navigation3 and org/koin rules. Leave both generated files in the working tree for review with the localized messages. Run this even for empty notes and releases without startup changes; never move generation into publishing CI. If recording is blocked, finish the resources and draft, report the exact blocker and command still needed, and do not claim the release preparation is complete.

9. Write the draft to .release-notes/<version>.md (create the directory; /.release-notes/ is gitignored, so these scratch files stay untracked). The file's contents are the release body and nothing else — no preamble, no headings above the bullets, no "generated by", no meta commentary — ending in the hidden store block described below. For empty notes omit the visible bullets and leave the whats-new en-US block empty; still include every store-control comment. Never write a second draft file. The tracked resources and generated profiles above are required changes, not extra drafts. Then tell the user, briefly:

   • whether the in-app message was updated or cleared, and whether both Android profiles were regenerated;
   • the path, and that the file is a throwaway to delete after pasting;
   • to paste all of it into the description of a new release tagged <version> on the commit that carries that campfire.versionName (publish-all.yml refuses a tag that disagrees with it), with "Set as a pre-release" left off, since a pre-release ships nothing;
   • that publishing the release is what ships it: publish-all.yml sends the builds to Play and the website, submits the iOS and macOS builds for App Review and the Windows build for Microsoft Store certification (each published as soon as it passes), and attaches the Linux packages to the release itself — so the notes never list or link downloads.

10. Do not create the tag, the release, or commit anything. Leave the draft, resources and generated profiles ready for review. Their commit must be included in the version's tag before publishing.