Compare the release candidate with the last release tag, and compare the package you are about to publish with the version already published. Read dependency changes, install scripts, workflow files and new binary or generated files first, because that is where surprises hide.
Two diffs, not one
Reviewing pull requests one by one is not the same as reviewing the whole release. Changes combine. A harmless looking dependency bump plus a changed build script can add up to something you would not accept in a single review.
- Source diff. What changed between the previous tag and the commit you will tag.
- Package diff. What changed between the previously published package and the one you are about to publish.
Source diff
git diff v2.3.0..HEAD --stat
git diff v2.3.0..HEAD -- package.json package-lock.json .github/
git log v2.3.0..HEAD --format='%h %an %s'
Read the stat first to find unexpected large or binary files. Then the manifest and lockfile changes, then the workflow directory. Then the authors list, looking for commit authors you do not recognise.
Package diff
For npm, the CLI includes a diff command. Its documentation describes it as similar to git diff, printing diff patches of files for packages in the registry or local folders. A typical use is comparing the published version with what is in your working tree:
npm diff --diff=my-package@2.3.0 --diff=.
Check the current npm documentation for exact arguments. The npm pack command can also write the tarball without publishing, and its dry run option reports what would happen without making changes.
For other ecosystems, build the artifact, unpack both versions, and use a normal directory diff.
What to look for
| Change | Question to ask |
|---|---|
| New or changed dependency | Why is it needed, who maintains it, what does it pull in |
| Changed install or build script | Does it download or run anything new |
| Edited workflow file | Did permissions or triggers widen |
| New binary or minified file | Where did it come from, can it be rebuilt |
| New files in the package that are not in git | Why is the package different from the source |
| Changed author or maintainer metadata | Was that intended |
A package containing files that are not in the repository is a particular red flag, because it means the release was built from something other than the tagged source.
Make it routine
Put the diff output in the release pull request or release issue, and have a second person read the dependency and workflow parts. If you are the only maintainer, read it the next morning rather than right after writing it.
Try it yourself
Click through it at your own pace, or open it full screen.
Open the dependency inventory and imagine it for the last tag and for the release candidate. The difference between them is your dependency review.
Quick check
Is a green CI run a substitute for reading the diff?
No. Tests show behaviour you thought to test. A diff shows what changed, including things no test covers.
Why diff the package and not just the source?
Because the package is what users install. If it contains files that are not in the tagged source, something in your build or publish path needs explaining.
Sources
Last reviewed: 19 October 2026.
