Skip to content

docs: follow librustzcash's changelog rules in the zc skill - #10

Merged
upbqdn merged 1 commit into
mainfrom
docs/lrz-changelog-rules
Jul 31, 2026
Merged

docs: follow librustzcash's changelog rules in the zc skill#10
upbqdn merged 1 commit into
mainfrom
docs/lrz-changelog-rules

Conversation

@upbqdn

@upbqdn upbqdn commented Jul 31, 2026

Copy link
Copy Markdown
Member

Motivation

zc drafts changelogs in librustzcash style, and the skill is what turns a draft into
committed entries. It covered lrz's formatting — section order, no ### Breaking Changes
section, periods, brace-group layout — but none of the rules that decide whether an entry is
required at all, what it says, or where it lands. Read against lrz's
Changelog Entries,
eight rules were missing and one was contradicted.

Solution

Add the missing rules to skills/zc/SKILL.md and skills/zc/REFERENCE.md:

  • What requires an entry (new section): bug fixes; semantic changes that leave signatures
    untouched (stricter validation, changed equality or ordering, a fixed value becoming
    configurable), which the API diff cannot see; the privacy, security, and cost properties of a
    public API; and a dependency bump whose types appear in the public API, since two
    semver-incompatible versions do not unify. Plus the exception: a crate that has never been
    released records only its initial release.
  • Reconcile with the unreleased section (new step): an entry describes the change since the
    crate's last release, not since zc's baseline. zc diffs the branch point, so a stacked or
    long-lived branch can produce a draft naming interstitial states no user ever saw. A rename
    yields one entry with the final name, an add-then-remove yields none, and existing entries are
    updated in place.
  • The entry belongs in the commit that makes the change, folded with git revise rather than
    appended as a trailing "update changelogs" commit. This replaces the previous instruction,
    which stopped at leaving the edits unstaged.
  • Released sections are a historical record — corrected only when wrong as written, never
    used to record later events — and the unreleased heading is permanent.
  • Added bullets are pointers: name the item, let its rustdoc explain it. Implementation
    details, internal refactors, and contracts invisible through the public API do not belong in a
    changelog.

Also documents which changelog a dependency bump belongs in. Crate changelogs are read by
downstream Rust code, so they carry it; an operator-facing binary changelog (Zebra's root
changelog) excludes dependency-only bumps unless they ship a security fix. That distinction came
up in zebra#11111.

Running zc --help now points at lrz's CONTRIBUTING for the curation rules, so the draft's own
output names its contract.

Tests

Docs and one comment block only; no behavior change. Ran locally: shellcheck -S warning zc tests/run.sh, bash -n zc, bash -n tests/run.sh.

The skill covered librustzcash's changelog *formatting* — section order, no
`### Breaking Changes` section, periods, brace groups — but none of the rules
that decide whether an entry is required, what it says, or where it lands.

Add the missing ones from librustzcash's CONTRIBUTING:

- Entries are required for bug fixes and for semantic changes that leave
  signatures untouched, which the API diff cannot see, plus the privacy,
  security, and cost properties of a public API.
- A dependency bump needs an entry when the dependency's types appear in the
  public API, because two semver-incompatible versions do not unify.
- A crate that has never been released records only its initial release.
- An entry describes the change since the crate's last release, not since the
  diff baseline; on a stacked branch the draft can name interstitial states, so
  existing `[Unreleased]` entries are updated in place instead of accumulating.
- The entry belongs in the commit that makes the change.
- Released version sections are a historical record, and the `[Unreleased]`
  heading is permanent.
- `Added` bullets are pointers to the item; implementation details do not
  belong in a changelog at all.

Also record which changelog a dependency bump belongs in: crate changelogs are
read by downstream Rust code, so they carry it, while an operator-facing binary
changelog excludes dependency-only bumps unless they ship a security fix.
@upbqdn
upbqdn merged commit d931229 into main Jul 31, 2026
2 checks passed
@upbqdn
upbqdn deleted the docs/lrz-changelog-rules branch July 31, 2026 16:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant