changelog

Files (1)

• SKILL.md

SKILL.md (first lines)

# MDK release changelog

Produce the changelog for the **next** release by investigating what actually
changed between the previous release tag and the current working tree — one
categorized entry per real change, anchored to concrete paths — then rotate the
old changelog into the archive (re-nested, prose untouched).

Target version: **$ARGUMENTS** (e.g. `0.5.0`). If empty, infer and confirm (see
Step 1). **Never** guess the version silently.

## Golden rules

- **Describe the release outcome, not the PR/commit narrative.** The changelog
  documents the *net difference* between the two release endpoints — what a consumer
  gets in the new version — not the sequence of PRs/commits that produced it. The
  linear `BASE..TARGET` tree diff is the source of truth for *what* changed; commits
  only explain *why* and reveal what to collapse. Two consequences you must enforce:
  - **Landed then reverted within the cycle → omit entirely.** Net effect is zero, so
    for this release it never happened. It will not appear in the tree diff; do not
    resurrect it from the commit log.
  - **Landed then refactored / renamed / superseded within the cycle → one entry for
    the final state only.** Never "added X (#1), then reworked X's API (#2)" — describe
    the X that actually ships, as a single entry.
- **"New" is a claim to check, not an assumption.** Before writing that something was *added*,
  *gained*, *now does* X, or gets a *new* Y, confirm it did not already exist at `BASE`:
  `git show BASE:<path>` for a file, or `git grep <symbol> BASE -- <path>` for a symbol. If it
  existed and merely changed, it belongs in `## Changed` describing *what* changed — never in
  `## Added`. Two failure modes this catches, both of which read as confident and are simply false:
  - **A pre-existing mechanism credited as new.** A method, poll, flag or dependency that was
    already there, whose *behavior* changed. Describe the behavior change, not the mechanism.
  - **The wrong cause credited for a real improvement.** Something that already existed gains one
    property (a backoff, a guard, an extra field) and the entry credits the whole mechanism. Name
    the property that actually changed.
  Run this check per item as you write, not as a review pass — it is one command and it is the
  single most common source of confidently wrong changelog entries.
- **A figure is a claim to verify, not a default to strip.** A count, size, or duration pulled from the diff (a case
  count, a file count, a percentage) is real information when it is accurate at `BASE..TARGET` — cutting it to sound
  safer throws that information away. Verify it against the thing it names (`wc -l`, the file it counts, the report
  that produced it), the same as any other claim, and keep it if it checks out. Only drop a figure that turns out
  wrong, or that names a one-off run with no fixture or report behind it (a self-reported "N trials" no test suite
  recorded) — the number isn't what disqualifies it, the absence of a reproducible source is.
  Prefer the delta over a bare snapshot when both endpoints are checkable (`262 → 273`, not just `273`): a lone count
  says nothing about direction or scale, but a before/after tells the reader what actually happened this release,
  and stays true as a historical fact regardless of what the count is next time.
- **Diff, don't paraphrase commit subjects.** Commit messages lie, squash, and
  omit. Read the real `git diff` for each area and describe what the code/docs
  actually do now. Commit history is only a map of *where* to look and *what to drop*.
- **The archived content is never rewritten, only re-nested.** When you rotate the
  current [`CHANGELOG.md`](../../CHANGELOG.md) into the archive, the *prose is untouched* — same wording,
  bullets, tables, links, and `#PR` refs. The only permitted changes are the
  mechanical re-nesting described in Step 3 (drop the title, add an `### Overview`
  header, demote every heading one level). Never re-summarize or "improve" archived
  content.
- **Match the house depth.** Existing entries use file paths, module/responsibility
  tables, and dependency lists. Aim for that specificity, not one-liners.
- **The changelog is prose — apply the docs style guide.**
  [`CHANGELOG.md`](../../CHANGELOG.md) is not exempt from
  [`docs/reference/maintainers/style.md`](../../docs/reference/maintainers/style.md). In particular wrap prose lines to
  **150–180 chars** (tables and fenced code are exempt), and follow its link and
  wording conventions. Read `style.md` before writing this file.
- **The changelog is a published artifact — no internal references.** Never cite
  PR/issue numbers, branch names, internal ticket ids, or contributor handles: to an
  outside reader they are dead links that mislink to unrelated items and expose internal
  development activity. Describe every change by its **outcome and code paths** only.
  Public identifiers (GHSA advisory ids, published package names/versions, the release
  tag) are fine. (Old archived entries may still contain such refs — leave them verbatim
  per the archive rule, but never add new ones.)
- **Keep confidential material out.** No real customer/site/device names or telemetry,
  no third-party/partner names, no unreleased or internal-only features or flag names,
  and no internal identifiers. Run whatever pre-publish leak check your project provides
  before handing off.
- **Draft only — do not commit, tag, or push.** Leave the files staged-but-uncommitted
  for the user to review.

## Layout this skill owns

| File | Role |
|---|---|
| [`CHANGELOG.md`](../../CHANGELOG.md) (repo root) | Detailed changelog for the **current** release. Header `# Changelog: mdk-X.Y.Z` → `## vX.Y.Z` → sections. |
| `docs/reference/changelog-archive/<year>-archive.md` | Past releases, appended in **ascending** order (newest at the bottom). Each entry is nested one level below the live changelog — top header `## vX.Y.Z`, sections `### …`, subsections `#### …` (see Step 3). |

## Step 1 — Establish the range and versions

```bash
git fetch --tags --quiet 2>/dev/null || true
PREV_TAG=$(git describe --tags --abbrev=0)      # previous release tag
echo "Previous tag: $PREV_TAG"
```

- **BASE** = the tag/ref you diff *from* (usually `$PREV_TAG`). **TARGET** = the ref you
  diff *to* — HEAD, or an explicit ref (e.g. a remote release branch) if the release is
  being cut there rather than on your checkout.
- **Range to investigate:** `BASE..TARGET`. If the user named two tags, use them.
- **`CUR_VERSION`** = version parsed from the existing [`CHANGELOG.md`](../../CHANGELOG.md) first line
  (`# Changelog: mdk-X.Y.Z`) **on TARGET** — `git show TARGET:CHANGELOG.md | head -1`,
  not necessarily your working copy. This is the release about to be archived.
- **`NEW_VERSION`** = `$ARGUMENTS` if given; else propose a bump from `$PREV_TAG`
  (patch/minor/major) and **ask the user to confirm** before writing anything.

**Guard against a divergent BASE — this is mandatory, not optional.** A tree diff
across two branches that have diverged is garbage: the commits unique to BASE show up
as *deletions*, so the changelog would list the previous release's own work as
"Removed." Verify BASE is a true ancestor of TARGET first:

```bash
git merge-base --is-ancestor "$BASE" "$TARGET" && echo "OK: linear" || echo "DIVERGENT — STOP"
git rev-list --count "$TARGET".."$BASE"    # commits in BASE missing from TARGET — must be 0
```

If it reports DIVERGENT (or the count is non-zero), **stop and report** — do not
generate from that range. Offer the fixes: pick a BASE that *is* an ancestor
(`git describe --tags TARGET`), or rebase/merge TARGET onto BASE first so the range
becomes linear.

Then sanity-check and report the plan before proceeding:
- If `NEW_VERSION == CUR_VERSION`, do **not** archive — the current CHANGELOG already
  targets this version; you are only refreshing it.
- If a `## vCUR_VERSION` header already exists in the archive, skip archiving (idempotent)
  and say so.

From tetherto/mdk, Apache-2.0.

More from tetherto/mdk