[DOCS] npm publish - lifecycle event order discrepancy

[summersk]

Is there an existing issue for this?

• I have searched the existing issues

This is a CLI Docs Problem, not another kind of Docs Problem.

• This is a CLI Docs Problem.

Description of Problem

The observed lifecycle events order for npm publish differ to the docs.

Observed

From verbose npm publish log (see repro below).

• prepublish
• prepare
• prepublishOnly
• prepack
• postpack
• publish
• postpublish

Repro

package.json

{
  "name": "@account-name/private-test",
  "version": "1.0.0",
  "description": "",
  "repository": "https://git.localhost/private-test",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "prepare": "echo \"### echo from package.json > scripts > prepare ###\"",
    "prepackageOnly": "echo \"### echo from package.json > scripts > prepackageOnly ###\"",
    "prepublish": "echo \"### echo from package.json > scripts > prepublish ###\"",
    "preprepare": "echo \"### echo from package.json > scripts > preprepare ###\"",
    "postpublish": "echo \"### echo from package.json > scripts > postpublish ###\""
  },
  "author": "",
  "license": "ISC"
}

index.js (empty)

// empty

npm --verbose publish

npm info it worked if it ends with ok
npm verb cli [
npm verb cli   '/home/redacted/.nvm/versions/node/v14.19.1/bin/node',
npm verb cli   '/home/redacted/.nvm/versions/node/v14.19.1/bin/npm',
npm verb cli   '--verbose',
npm verb cli   'publish'
npm verb cli ]
npm info using npm@6.14.16
npm info using node@v14.19.1
npm verb npm-session redacted
npm verb publish [ '.' ]
npm WARN prepublish-on-install As of npm@5, `prepublish` scripts are deprecated.
npm WARN prepublish-on-install Use `prepare` for build steps and `prepublishOnly` for upload-only.
npm WARN prepublish-on-install See the deprecation note in `npm help scripts` for more information.
npm info lifecycle @account-name/private-test@1.0.0~prepublish: @account-name/private-test@1.0.0

> @account-name/private-test@1.0.0 prepublish .
> echo "### echo from package.json > scripts > prepublish ###"

### echo from package.json > scripts > prepublish ###
npm verb lifecycle @account-name/private-test@1.0.0~prepublish: unsafe-perm in lifecycle true
npm verb lifecycle @account-name/private-test@1.0.0~prepublish: PATH: redacted
npm verb lifecycle @account-name/private-test@1.0.0~prepublish: CWD: .
npm info lifecycle @account-name/private-test@1.0.0~prepare: @account-name/private-test@1.0.0

> @account-name/private-test@1.0.0 prepare .
> echo "### echo from package.json > scripts > prepare ###"

### echo from package.json > scripts > prepare ###
npm verb lifecycle @account-name/private-test@1.0.0~prepare: unsafe-perm in lifecycle true
npm verb lifecycle @account-name/private-test@1.0.0~prepare: PATH: redacted
npm verb lifecycle @account-name/private-test@1.0.0~prepare: CWD: .
npm info lifecycle @account-name/private-test@1.0.0~prepublishOnly: @account-name/private-test@1.0.0
npm info lifecycle @account-name/private-test@1.0.0~prepack: @account-name/private-test@1.0.0
npm info lifecycle @account-name/private-test@1.0.0~postpack: @account-name/private-test@1.0.0
npm notice 
npm notice 📦  @account-name/private-test@1.0.0
npm notice === Tarball Contents === 
npm notice 0    index.js    
npm notice 700B package.json
npm notice === Tarball Details === 
npm notice name:          @account-name/private-test              
npm notice version:       1.0.0                                   
npm notice package size:  376 B                                   
npm notice unpacked size: 700 B                                   
npm notice shasum:        redacted
npm notice integrity:     redacted
npm notice total files:   2                                       
npm notice 
npm http fetch PUT 201 redacted/@account-name%2fprivate-test
npm info lifecycle @account-name/private-test@1.0.0~publish: @account-name/private-test@1.0.0
npm info lifecycle @account-name/private-test@1.0.0~postpublish: @account-name/private-test@1.0.0

> @account-name/private-test@1.0.0 postpublish .
> echo "### echo from package.json > scripts > postpublish ###"

### echo from package.json > scripts > postpublish ###
npm verb lifecycle @account-name/private-test@1.0.0~postpublish: unsafe-perm in lifecycle true
npm verb lifecycle @account-name/private-test@1.0.0~postpublish: PATH: redacted
npm verb lifecycle @account-name/private-test@1.0.0~postpublish: CWD: .
+ @account-name/private-test@1.0.0
npm verb exit [ 0, true ]
npm timing npm Completed in 307ms
npm info ok

• npm v6.14.16
• node v14.19.1

Docs

v6-docs - https://docs.npmjs.com/cli/v6/using-npm/scripts

npm publish

• prepublishOnly
• prepare
• prepublish
• publish
• postpublish

latest - https://docs.npmjs.com/cli/v8/using-npm/scripts

npm publish

• prepublishOnly
• prepack
• prepare
• postpack
• publish
• postpublish

Potential Solution

Is a docs update in order here?

Happy to PR - just wanted to check I wasn't missing anything first... :)

Affected URL

https://docs.npmjs.com/cli/v8/using-npm/scripts#npm-publish

[ljharb]

npm 6 is EOL. what does npm 8 do? (that's the only version that matters)

[summersk]

I should have mentioned initially, both versions of the docs contradict themselves:

prepare (since npm@4.0.0)

• ...
• Run AFTER prepublish, but BEFORE prepublishOnly
• ...

A quick check of npm from latest appears* to be in line with the v8 docs:

• prepublishOnly
• prepack
• prepare
• postpack
• publish
• postpublish

*appears: --verbose and foreground-scripts:true wouldn't log all events, had to trace runScript / npmcli/run-script 🤷

Not looking to change any behavior for v6, just update the docs for the next poor soul ;)