Say which package changed, from which version to which, why, who is affected, and what app teams must do. Skip entries for bumps that change nothing a consumer could notice. A changelog line is useful when it lets a reader decide whether to act today.
Why consumers read the changelog
App teams skim release notes to decide whether to take an update this week. A line reading "updated dependencies" tells them nothing. They cannot tell a routine refresh from a security fix, a peer range change or a new minimum Node version.
A template
Use a short block per notable dependency change:
- Package and versions: name, old version, new version.
- Reason: security advisory identifier, bug fix, or maintenance.
- Effect on you: what changes in behavior, size, or install requirements.
- Action required: none, or a specific step such as raising a peer version.
- Risk note: whether any visual or behavior change is expected.
What to include and what to leave out
| Change | In the changelog? |
|---|---|
| Security fix in a runtime dependency | Yes, with advisory ID and action |
| Peer dependency range widened or narrowed | Yes, always |
| New runtime dependency added | Yes, consumers inherit it |
| Dev tool patch bump | No |
| Minimum Node version raised | Yes |
| Bundled dependency updated | Yes, since apps cannot patch it themselves |
For the bundled case, see do scanners see dependencies bundled inside a UI library build.
Versioning signals
Under semantic versioning, as published at semver.org, a major is for incompatible changes, a minor for compatible new functionality, and a patch for compatible fixes. Narrowing a peer range can break installs for apps outside it, so treat it as breaking even if no code changed. Widening it is usually compatible. Your changelog should agree with the version number: a reader seeing "patch" should not find a required action.
Security advisories
When a dependency fix matters, add a clear heading, link the public advisory, say which of your versions are affected and which contain the fix, and state whether apps need to update their lockfiles. Do not overstate: if you have not verified exploitability in your components, say that you are assessing, and update the note later. Keep to facts and avoid legal wording.
A worked example
Suppose your library updates a sanitizing package because of a published advisory. A useful entry names the package and both versions, links the advisory, says which library versions are affected and which contain the fix, and states the action: take the new release and refresh the lockfile. A weak entry says "bumped dependencies" and leaves each team to dig through the diff. The first takes two minutes to write and saves every reader the same time.
If the bump also changes bundle size or adds a transitive package, say so. Readers watching bundle budgets will thank you, and it makes later regressions easier to trace to a release.
Make it findable
Put the changelog in the package and on the docs site, and mirror breaking items in the release announcement. Automated tools can read well structured notes, and bots often paste them into update pull requests, so clear writing helps every consuming team review faster.
Safeguard can show which apps still use an affected library version after your advisory, so the follow up does not rely on people reading the note. A free scan is at gold.safeguard.sh/scan.
Quick check
Should every dependency bump get an entry?
No. Record those a consumer could notice: security fixes, runtime additions, peer changes, runtime floors.
Is narrowing a peer range a patch?
It can break installs, so treat it as a breaking change and version it accordingly.
Sources
Last reviewed: 19 October 2026.
