[BUG] CHANGELOG not included by default by npm pack / publish

[TomStrepsil]

Is there an existing issue for this?

• I have searched the existing issues

This issue exists in the latest npm version

• I am using the latest npm

Current Behavior

When running npm publish or npm pack, CHANGELOG (or variants) in the root of a package does not appear to be included in package output.

The developer documentation states:

The following paths and files are never ignored, so adding them to .npmignore is pointless:

package.json
README (and its variants)
CHANGELOG (and its variants)
LICENSE / LICENCE

...this is in contrast to the documentation on "files" which states:

Certain files are always included, regardless of settings:

package.json
README
LICENSE / LICENCE
The file in the "main" field
The file(s) in the "bin" field

Does the developer documentation need to be updated in-line with "files"?

Expected Behaviour

CHANGELOG (and variants) should be included in package output

Steps To Reproduce

• add CHANGELOG (or variant e.g. CHANGELOG.md) to root of a package
• run npm publish --dry-run

Environment

• npm: 11.4.2
• Node.js: 22.14.0
• OS Name: Mac OS Sequoia 15.5 (24F74)
• System Model Name: MacBook Pro

[ljharb]

I believe the docs are correct - meaning, you have to add CHANGELOG manually with files, but you don't have to worry about it with npmignore?

[TomStrepsil]

Ah OK - interesting that, without any use of "files", package.json, README.md etc. are included in pack / publish by default, but CHANGELOG is not.

The statement:

The following paths and files are never ignored, so adding them to .npmignore is pointless

...seems incongruous - the intent is, if it's added (manually) to "files", it cannot subsequently be ignored via .npmignore?

By default, an .npmignore of:

*

...will exclude the changelog, and needs:

*
!CHANGELOG

...to have it included (unlike the other files mentioned). So unclear what "never ignored" means in relation to this file.

[ljharb]

It means that when using npmignore, you can't keep the changelog out. When using files, you have to choose to keep the changelog in.

[TomStrepsil]

OK - so when not using "files", you have to explicitly exclude CHANGELOG from .npmignore, otherwise is is ignored by default. Hence "never ignored" seems like confusing wording.

But - I take the sentiment, these are separate concepts, and perhaps I've just conflated things. The fact that package.json and README are in the venn is perhaps what's caused my confusion.

[TomStrepsil]

Interestingly, the statement:

The following paths and files are never ignored, so adding them to .npmignore is pointless:
...
CHANGELOG (and its variants)

...does not seem to apply, with a basic test.

See here - when included in .npmignore, the output of npm pack --dry-run is:

npm notice === Tarball Contents === 
npm notice 7B   README.md   
npm notice 34B  index.js    
npm notice 158B package.json
npm notice === Tarball Details === 

...whereas removing CHANGELOG.md from .npmignore produces:

npm notice === Tarball Contents === 
npm notice 7B   CHANGELOG.md
npm notice 7B   README.md   
npm notice 34B  index.js    
npm notice 158B package.json
npm notice === Tarball Details === 

[milaninfy]

@TomStrepsil I believe the documentation link you provided is from v9 docs
That changelog bit was corrected in this PR #8295
here is the v11 docs link https://docs.npmjs.com/cli/v11/using-npm/developers#keeping-files-out-of-your-package

The following paths and files are never ignored, so adding them to .npmignore is pointless:

package.json
README (and its variants)
LICENSE / LICENCE

[TomStrepsil]

@milaninfy - oh wow, so sorry for not spotting I had linked to an out-of-date version of the docs 🫣

Makes complete sense now, I guess CHANGELOG was deemed package-worthy in the past, and opinion has shifted.

Thanks so much for clarification.