docs: follow librustzcash's changelog rules in the zc skill - #10
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 Changessection, 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.mdandskills/zc/REFERENCE.md: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.
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.
git reviserather thanappended as a trailing "update changelogs" commit. This replaces the previous instruction,
which stopped at leaving the edits unstaged.
used to record later events — and the unreleased heading is permanent.
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 --helpnow points at lrz's CONTRIBUTING for the curation rules, so the draft's ownoutput 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.