Skip to content

Commit 98e2a41

Browse files
committed
docs: Add changelog update instructions to readme
1 parent 8ad0cbd commit 98e2a41

1 file changed

Lines changed: 32 additions & 1 deletion

File tree

README.md

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,9 +62,40 @@ purposes only.
6262

6363
See [`packages/create-package/README.md`](packages/create-package/README.md).
6464

65+
### Updating changelogs
66+
67+
Each package in this repo has a file named `CHANGELOG.md` which is used to
68+
record consumer-facing changes that have been published over time. All
69+
changelogs follow the ["Keep a Changelog"](https://keepachangelog.com/)
70+
specification (enforced by `@metamask/auto-changelog`).
71+
72+
If a PR introduces a consumer-facing change to one or more packages, their changelogs must
73+
be updated. This is enforced by CI. When updating changelogs, keep the following in mind:
74+
75+
- A changelog is not a git history; it is a summary of consumer-facing changes introduced by
76+
a particular release.
77+
- Consider each PR from the perspective of a consumer of an individual package. Changelog
78+
entries may differ between packages.
79+
- For example, if you're introducing feature X to package A, and it contains an incidental
80+
change Y to package B, the package changelogs should reflect this.
81+
- Place new entries under the "Unreleased" section.
82+
- Place changes into categories. Consult the ["Keep a Changelog"](https://keepachangelog.com/en/1.1.0/#how) specification for the list.
83+
- Highlight breaking changes by prefixing them with `**BREAKING:**`.
84+
- Omit non-consumer facing changes from the changelog.
85+
- Do not simply reuse the commit message, but describe exact changes to the API or usable
86+
surface area of the project.
87+
- Use a list nested under a changelog entry to enumerate more details about a change if need be.
88+
- Include links (e.g. `#123) to the pull request(s) that introduced each change.
89+
- Combine like changes from multiple pull requests into a single changelog entry if necessary.
90+
- Split disparate changes from the same pull request into multiple entries if necessary.
91+
- Omit reverted changes from the changelog.
92+
93+
If your PR does not contain any consumer-facing changes, add the label `no-changelog`, and the
94+
changelog validation CI job will be skipped.
95+
6596
### Releasing
6697

67-
For information on creating releases, see the [MetaMask/core release documentation](https://github.com/MetaMask/core/blob/main/docs/contributing.md#releasing-changes).
98+
For information on creating releases, see the [MetaMask/core release documentation](https://github.com/MetaMask/core/blob/d6ce6e1c917b1a05356df365281a5db83f500210/docs/processes/releasing.md).
6899

69100
### Patches
70101

0 commit comments

Comments
 (0)