Skip to content

docs: correct the changelog guidelines - #11124

Open
upbqdn wants to merge 1 commit into
mainfrom
11123-fix-dev-docs
Open

docs: correct the changelog guidelines#11124
upbqdn wants to merge 1 commit into
mainfrom
11123-fix-dev-docs

Conversation

@upbqdn

@upbqdn upbqdn commented Jul 27, 2026

Copy link
Copy Markdown
Member

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 to
changie. One commit on book/src/dev/changelog-guidelines.md:

  • Section order. The list cited Keep a Changelog order while leading with
    Breaking Changes. That section is real — it is the breaking kind in
    .changie.yaml — so the text now says the order is the kinds list: Zebra's
    breaking first, then Keep a Changelog order.
  • Double-listing exception dropped. It contradicted the one-entry-per-change
    rule stated just above it. The priority order already files a
    breaking-and-additive change under Breaking Changes; the entry just has to
    name the new capability too. The text now draws the distinction the exception
    was blurring: zebra-chain 12.0.0 lists fix(chain)!: validate the total amount when updating a value balance #10817's new
    ValueBalanceError::Total under Breaking Changes and its new
    ValueBalance::total under Added because those are two changes, not one
    change filed twice.
  • New Dependency updates section. A crate changelog needs an entry when a
    dependency 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.yaml maps Changed to a minor bump, which would ship a consumer
    build break in a minor release. A semver-compatible bump unifies, so it gets a
    Changed entry 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_primitives 0.30.0 entry came to be dropped in chore: Update to zcash_primitives version 0.30.0 #11111. The zebrad row
    now says it applies to that file only, and the "deciding where to document"
    table gains the dependency and MSRV rows.
  • Stale versions. The compatibility template quoted NU6.1 and Rust 1.75; it
    now shows NU6.3 and the 1.91 zebrad / 1.88 workspace split, and says to fill
    the table from rust-version rather than copy it. The crate-breaking table's
    MSRV row quoted 1.70 to 1.75; it now reads "rust-version raised to a newer
    stable", 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 against
zebra_rpc::MinerParams::addr and the zcash_keys version in the workspace
manifest, and the MSRV values against rust-version.

AI Disclosure

  • No AI tools were used in this PR
  • AI tools were used: Claude, to find the inconsistencies and draft the changes.

PR Checklist

  • The PR title follows conventional commits format: type(scope): description
  • The PR follows the contribution guidelines.
  • This change was discussed in an issue or with the team beforehand.
  • The solution is tested.
  • The documentation and changelogs are up to date.

@upbqdn
upbqdn force-pushed the 11123-fix-dev-docs branch from e74326e to 3a75a96 Compare July 27, 2026 23:35
@upbqdn
upbqdn force-pushed the 11123-fix-dev-docs branch 2 times, most recently from 752af8a to 681b827 Compare September 4, 2026 12:20
@upbqdn upbqdn changed the title docs: correct the merge-policy and changelog guidance docs: correct the changelog guidelines Sep 4, 2026
@upbqdn
upbqdn marked this pull request as ready for review September 4, 2026 12:20
@v12-auditor

v12-auditor Bot commented Sep 4, 2026

Copy link
Copy Markdown

Warning

No auditable source files found in this PR's diff.

@upbqdn
upbqdn force-pushed the 11123-fix-dev-docs branch from 681b827 to 551a34f Compare September 4, 2026 12:22
@upbqdn upbqdn self-assigned this Sep 4, 2026
@upbqdn
upbqdn force-pushed the 11123-fix-dev-docs branch from 551a34f to b99bd64 Compare September 4, 2026 12:27
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
upbqdn force-pushed the 11123-fix-dev-docs branch from b99bd64 to d4a4b77 Compare September 4, 2026 12:59
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.

docs: correct the merge-policy and changelog guidance in the dev docs

1 participant