docs: correct the changelog guidelines - #11124
Open
upbqdn wants to merge 1 commit into
Open
Conversation
upbqdn
force-pushed
the
11123-fix-dev-docs
branch
from
July 27, 2026 23:35
e74326e to
3a75a96
Compare
upbqdn
force-pushed
the
11123-fix-dev-docs
branch
2 times, most recently
from
September 4, 2026 12:20
752af8a to
681b827
Compare
upbqdn
marked this pull request as ready for review
September 4, 2026 12:20
|
Warning No auditable source files found in this PR's diff. |
upbqdn
force-pushed
the
11123-fix-dev-docs
branch
from
September 4, 2026 12:22
681b827 to
551a34f
Compare
upbqdn
force-pushed
the
11123-fix-dev-docs
branch
from
September 4, 2026 12:27
551a34f to
b99bd64
Compare
The section list cited Keep a Changelog order while leading with Zebra's `Breaking Changes` section, which comes from the `breaking` kind in `.changie.yaml`. Say where the order comes from instead. The double-listing exception contradicted the one-entry-per-change rule stated just above it, and the crate changelogs list such a change once, so drop it. Nothing covered dependency updates in crate changelogs, and read out of context the zebrad exclusion looks global — which is how the `zcash_primitives` 0.30.0 entry came to be dropped in #11111. Add a `Dependency updates` section, scope the zebrad row to that file, and give the "deciding where to document" table dependency and MSRV rows. The MSRV example quoted 1.70 to 1.75 and the compatibility template NU6.1 and Rust 1.75; use the current versions and point at `rust-version`.
upbqdn
force-pushed
the
11123-fix-dev-docs
branch
from
September 4, 2026 12:59
b99bd64 to
d4a4b77
Compare
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
Closes #11123.
Solution
The merge-policy half of the issue landed in #11285, so this is the changelog
half only, rebased onto current
main, where the changelogs have since moved tochangie. One commit on
book/src/dev/changelog-guidelines.md:Breaking Changes. That section is real — it is thebreakingkind in.changie.yaml— so the text now says the order is thekindslist: Zebra'sbreakingfirst, then Keep a Changelog order.rule stated just above it. The priority order already files a
breaking-and-additive change under
Breaking Changes; the entry just has toname the new capability too. The text now draws the distinction the exception
was blurring:
zebra-chain12.0.0 lists fix(chain)!: validate the total amount when updating a value balance #10817's newValueBalanceError::TotalunderBreaking Changesand its newValueBalance::totalunderAddedbecause those are two changes, not onechange filed twice.
Dependency updatessection. A crate changelog needs an entry when adependency moves to a semver-incompatible version whose types appear in the
crate's public API: the two versions do not unify, so consumers have to move
with the bump. That is breaking, so the fragment kind is
breaking—.changie.yamlmapsChangedto a minor bump, which would ship a consumerbuild break in a minor release. A semver-compatible bump unifies, so it gets a
Changedentry only when consumers notice it. Nothing covered any of this,and read out of context the zebrad exclusion looks global — which is how the
zcash_primitives0.30.0 entry came to be dropped in chore: Update to zcash_primitives version 0.30.0 #11111. The zebrad rownow says it applies to that file only, and the "deciding where to document"
table gains the dependency and MSRV rows.
now shows NU6.3 and the 1.91
zebrad/ 1.88 workspace split, and says to fillthe table from
rust-versionrather than copy it. The crate-breaking table'sMSRV row quoted
1.70 to 1.75; it now reads "rust-versionraised to a newerstable", which cannot go stale.
Tests
Docs-only: no code path changes, so no test applies. What the text now asserts
is checkable against the repo instead — the kind list and its bump levels
against
.changie.yaml, the two-changes example against.changes/zebra-chain/v12.0.0.md, the dependency example againstzebra_rpc::MinerParams::addrand thezcash_keysversion in the workspacemanifest, and the MSRV values against
rust-version.AI Disclosure
PR Checklist
type(scope): description