From 20689b74e74de93d0952cd43a8fb422a9cb14b7a Mon Sep 17 00:00:00 2001 From: SpaiR Date: Mon, 27 Jul 2026 11:30:56 +0300 Subject: [PATCH] docs(contributing): document the release notes format Release notes were written from scratch each time, so the section order, the contributor credits and the ko-fi block drifted between releases. Codify the structure the recent releases converged on: mandatory sections, when the optional ones apply, how change lines credit contributors, and the Thanks block reproduced verbatim. Point the release procedure and AGENTS.md at it instead of restating a subset. Co-authored-by: Claude --- AGENTS.md | 3 +++ CONTRIBUTING.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 49 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8fb8709e..0753867d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -218,6 +218,9 @@ Use `providers.exec { ... }` for shell-outs, never `.execute()`. Capture resolve the full Dear ImGui version plus an imgui-java counter (`v1.92.7.1` = second release on Dear ImGui `1.92.7`), so a breaking change is only ever visible via `!`, the footer, the `breaking-change` label, and the release notes. Never cut a release on stale `bin/` natives. +- **Release notes** → "Release notes". Fixed section order, and the `### Thanks` block with the + ko-fi button is reproduced verbatim in every release — don't reword it or drop it. Start from + GitHub's generated notes, then rewrite them for the consumer. The rule that submodule bumps, Gradle/deps bumps, and codegen-tooling changes each go in their own PR is in `.claude/rules/guardrails.md` ("Don't merge submodule bumps with feature work") diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 55ca5949..f1514adb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -376,6 +376,51 @@ GitHub release notes. Nothing else surfaces them. There is no version file to bump. `build.gradle` derives the version from `git describe --tags` (leading `v` stripped), so **the tag is the version of record**. +### Release notes + +Every release gets hand-written notes on the draft. Start from GitHub's **Generate release notes** button and rewrite +what it produces — ship it raw only on a pure patch release with no user-visible change. + +Sections, in this order. Only `What's Changed`, `List of changes`, `Thanks` and the changelog line are mandatory; the +rest appear when there is something to put in them. + +| Section | When | +|-----------------------------|-------------------------------------------------------------------| +| `## What's Changed` + lead | always — 1–3 sentences, and the lead always names the Dear ImGui version the release ships | +| `### ⚠️ Breaking changes` | if anything breaks callers — always first, with migration instructions | +| `### Highlights` | when the release has a headline; bold lead-in per bullet, detail nested underneath | +| `### Known limitations` | when something notable is deliberately not implemented; if unchanged from the previous release, say so and link it rather than repeating | +| `### Migration notes` | when calling code must change — before/after table, plus links to upstream release notes and the compare range | +| `### List of changes` | always — one line per merged PR | +| `### Contributors` | when someone outside the maintainer contributed; name what each person did | +| `## New Contributors` | keep GitHub's auto-generated block verbatim when it produced one | +| `### Thanks` | always — fixed block, see below | +| `**Full Changelog**: ` | always — last line of the notes | + +Writing rules: + +- **Write for the consumer, not the committer.** "Native artifacts target Java 8 again", not "fix release target in + `build.gradle`". Each line answers what changes for someone who depends on the library. +- **Change lines** read `* by @user in `. Credit external contributors; drop `by @` on the + maintainer's own PRs. Use full URLs, not `#123` — that is what the generator emits. +- **Breaking changes** get ⚠️ on the change line *and* the dedicated section. The version number cannot signal them, + see [Versioning](#versioning). +- **Build and tooling bumps** go in a `
` block, with an explicit note that they do not reach the published + artifacts and that `imgui-binding` still ships with zero runtime dependencies. Collapse repeated bumps of one + dependency into a single line with the full range. +- **Submodule bumps** always link both the upstream release notes and the compare range. +- **Thanks** is a fixed block — reproduce it verbatim, in every release: + ```md + ### Thanks + + **Thanks to all contributors and users for your valuable feedback and support! + You can support the project's development with a donation - your contribution helps keep it growing and improving.** + + [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/P5P5BF17Q) + ``` + +The release title is the tag (`v1.92.7.1`). The draft stays a draft until the notes are proofread. + ### Cutting a release 1. Make sure `main` is green and `bin/` is current — the `update-bin` job must have run after the last binding change. @@ -394,8 +439,7 @@ so **the tag is the version of record**. 4. The `release` job runs on the tag: builds Java, builds all three natives, publishes every module and native classifier to Maven Central via `buildSrc/scripts/publish.sh`, then opens a **draft** GitHub release with `java-libraries.zip` and `native-libraries.zip` attached. -5. Write the release notes on the draft and publish it. Group by `feat` / `fix` / `build`, and give breaking changes - their own section at the top with migration instructions. +5. Write the release notes on the draft following [Release notes](#release-notes), proofread them, then publish. 6. Verify the artifacts appear on Maven Central under `io.github.spair`. ## Contributing with AI agents