paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 44 Packages Projects Releases Wiki Activity

docs: clarify that changesets should not reference internal code details

Browse Source 
Update changeset writing guidance in AGENTS.md, CONTRIBUTING.md, and
REVIEWING.md to explicitly state that changeset messages should never
mention internal implementation details such as internal function names,
class names, variable names, or other code symbols. Messages should
describe user-facing behavior changes in plain language.

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
Made-with: Cursor
This commit is contained in:
Patrik Oldsberg
2026-04-16 23:21:56 +02:00
parent 180890ef94
commit b2fd456ba4
3 changed files with 7 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
REVIEWING.md
+2 -2
View File
@@ -135,11 +135,11 @@ Each changeset should be written in a way that describes the impact of the chang
Some things that changeset should NOT contain are:
- Internal architecture details - these are generally not interesting to users, focus on the impact towards users of the package instead.
- Internal implementation details such as internal function names, class names, variable names, or other code symbols that are not part of the public API. Changeset messages should describe user-facing behavior changes in plain language. Focus on the impact towards users of the package, not on how the code is structured internally.
- Information related to a different package.
- A large amount of content, consider for example a separate migration guide instead, either in the package README or [./docs/](./docs/), and then link to that instead.
- Documentation - changesets can describe new features, but it should not be relied on for documenting them. Documentation should either be placed in [TSDoc](https://tsdoc.org) comments, package README, or [./docs/](./docs/).
- Diffs of internal code, for example mirroring what the pull request changes _inside_ a plugin rather than public surfaces. This is not of interest to the reader of a package changelog. Sometimes, however, a small and concise diff can be used in a changeset to illustrate changes that the user will have to make in _their own_ Backstage installation as part of an upgrade, specifically when breaking changes are made to a package.
- Diffs of internal code, for example mirroring what the pull request changes _inside_ a plugin rather than public surfaces. This is not of interest to the reader of a package changelog, and internal function names, class names, or variable names should never appear in changeset messages. Sometimes, however, a small and concise diff can be used in a changeset to illustrate changes that the user will have to make in _their own_ Backstage installation as part of an upgrade, specifically when breaking changes are made to a package.
### Backstage UI Changeset Format