Changelog conventions
Changelog conventions
Section titled “Changelog conventions”This page defines the contract every public NextPDF repository follows when it
records a change and publishes a release. It is a convention reference; it does
not define package behavior. Per-package, per-version release notes live in each
repository’s own CHANGELOG.md. These shared rules keep the
cross-repo changelog summary consistent and leak-free.
Conventional Commits 1.0.0
Section titled “Conventional Commits 1.0.0”Every commit subject uses type(scope): description. The type is one of:
| Type | Meaning | User-facing | Version effect |
|---|---|---|---|
feat | New capability | yes | minor bump |
fix | Corrected behavior | yes | patch bump |
perf | Performance improvement with no behavior change | yes | patch bump |
refactor | Internal restructuring with no observable change | no | none |
docs | Documentation only | no | none |
test | Tests only | no | none |
build / ci | Build or pipeline only | no | none |
chore | Maintenance, dependencies, or tooling | no | none |
revert | Revert of a prior commit | depends | depends |
A breaking change uses a ! after the type or scope (feat(api)!: …) or a
BREAKING CHANGE: footer. Either marker raises the major version under
Semantic Versioning. Record a security-relevant fix so it can appear in the
Security column of the cross-repo summary.
Semantic Versioning 2.0.0
Section titled “Semantic Versioning 2.0.0”Version bumps are mechanical. A release that contains any breaking change is a
major. Otherwise, a release that contains any feat is a minor. Otherwise, a
release that contains any fix or perf is a patch. Pre-1.0 packages may bump
the minor for a breaking change per SemVer §4. The commit still carries the
breaking marker so the summary stays accurate.
Keep a Changelog grouping
Section titled “Keep a Changelog grouping”Each repository’s CHANGELOG.md follows
Keep a Changelog 1.1.0: entries are
grouped by released version under Added, Changed, Deprecated, Removed,
Fixed, and Security. An [Unreleased] section may hold in-progress notes
in the repository, but the cross-repo summary counts only
tagged, released versions. Unreleased work never appears in the public
index.
How the cross-repo summary is derived (and kept leak-free)
Section titled “How the cross-repo summary is derived (and kept leak-free)”The summary table on the changelog index is produced by reading each repository’s Conventional Commits history at its latest released tag, read-only, and counting categories. The derivation rules are deliberately narrow so internal detail does not escape:
- Counts, not content. Only the number of commits per user-facing type is reported. No commit subject, body, footer, or hash is rendered.
- User-facing types only.
docs,test,ci,chore, andrefactorare excluded because they change nothing a package consumer observes. - Released only. A commit counts only after it becomes part of a tagged release of a public package.
- No identifiers. Internal issue, ticket, cycle, wave, or work-item references that may appear in a private commit scope are never surfaced, because the scope text itself is never rendered. Only the type is read.
- No automation attribution. Contributor-automation trailers are not read or displayed.
For that reason, the public changelog is a category summary with links to each
package’s own CHANGELOG.md, not an aggregated commit feed. The summary is
free of internal leakage by construction. Authoritative release prose stays
with the package that owns it.