node: Remove outdated caveat as of #22408

[claui]

This PR removes an outdated caveat when building node --with-npm.

Rationale

When building the node formula --with-npm (which is the default), Homebrew still displays the following caveat:

If you update npm itself do NOT use the npm upgrade command
Instead execute:
npm install -g npm@latest

The caveat seems confusing/misleading to me in the following ways:

• As @ijy states in Homebrew installed npm can't upgrade itself #22408, the workaround has become obsolete since PR node: install npm using tarball. #28075.
  The latter fixes both New formula: distribute #1564 and Homebrew installed npm can't upgrade itself #22408; I figure this makes the caveat obsolete, too.
• Also, nitpicky me says there is no such thing as npm upgrade. (Did you mean npm update?)

Please review

I have left the second caveat untouched. I assume it is still relevant?
Could anyone with more in-depth knowledge please review and confirm that it’s OK to leave it that way?

Thanks in advance!

[claui]

Pinging @MikeMcQuaid who kindly authored the original PR.

[MikeMcQuaid]

Thanks for the PR! I'll need to call in @DomT4 here as I'm not totally sure.

[DomT4]

Thanks for the ping. So, you're semi-correct, but not quite for the reasons given. (I mean no offence by this at all). npm update is indeed what I meant, rather than upgrade - The fact I haven't noticed that till you just pointed it out astounds me. I'll add that to the growing tally of stupid things I haven't noticed recently 😧.

However, Although the message was borked on the update/upgrade wording, It remains true in intention. See the line referencing commit 8fe0081 in this file. Upstream also recommend the way to update npm is to do npm install -g npm which you can see in this documentation change at the time, a change that does persist to this day. There are issues around the npm update command and what it fundamentally is supposed to do, which you can keep track of in this issue.

The upstream recommendation is to still do npm install npm -g or npm install npm@latest -g to update your npm version. npm upstream have been making changes to try and lessen the fatality caused by updating it globally with the update command, which is why we see the issue considerably less these days, but IMO rather than removing the caveat entirely we should move towards rewording it along the lines of instead of doing npm update -g npm etc etc etc do npm install -g npm@latest. The upstream advice remains the same, even if I screwed the wording up 😊.

[DomT4]

For completeness: The issues you referenced in your post here are unrelated to the issue we were trying to tackle with that caveat. Those issues were actually about the way Homebrew installs npm in the first place - The way I understand it is that Homebrew used to have both a Node & npm formula, and the two were essentially joined. This caused huge issues in the way npm could be updated internally because of various symlink conflict that would happen, and in the end as you highlight Homebrew scrapped the separate formulae and started shipping an npm tarball inside the Node formula and dealing with things that way rather than trying to meld the two separate formulae together.

As Mike writes in this comment the way we handle npm now is similar to the way we handle pip, and when you install Python you get this caveat Setuptools and Pip have been installed. To update them: pip install --upgrade pip. So Homebrew explicitly supports people who want to update their pip or npm or whatever once the formulae are installed; The problem with npm arose because npm update -g npm has been broken since the dawn of time itself and would break almost all of the permissions Homebrew needs to function and overwrite things, which is an issue upstream have been working on for some time and making progress on, but upstream still recommend doing the npm install -g npm@latest dance to update the actual npm tool itself.

[claui]

Oh wow! Thank you @DomT4 for taking the time to clear things up!

Sorry – I was truly confused by that katamari of different issues involving npm update. Your explanation helped a lot.

So … if I understand you correctly, the thing is: although Homebrew (as of PR #28075) no longer stands in the way of npm upgrading itself, npm update -g npm still has issues on its own, right?

To me, the current caveat as it stands always screamed: »Listen, npm has this nice thing called npm update -g npm, but Homebrew just broke it because we don’t feel like doing it right. So you had better use this workaround.«

How about just slightly rephrasing the caveat? Simply to make users feel a bit more at ease, making it a tad more obvious that we’re talking about a recommended (upstream-endorsed) thing, nothing more? Let alone a crutch introduced by Homebrew not doing its homework?

Updated the PR. What do you think?

[DomT4]

Apologies for the walls of text there. The issue is quite a long and complicated one, and trying to concisely explain the history of the various intertwined problems is a challenge I fail at, heh. But yes, certainly between the way Homebrew used to deal with npm and the upstream problems, I can appreciate that it looks hella confusing for most people, and perhaps at the time we put the caveat in we should have covered some of that history in way of explanation, but I think by the time we put the caveat in the general attitude from everyone was more or less "Geez, I hope this keeps things from falling apart so regularly" 😁.

But yes, to answer your question here, nothing about Homebrew or its mechanisms themselves stands in the way of users updating their own npm versions as often as they like. npm is essentially on par with pip in terms of that sort of thing. The issues around npm update -g npm are recognised upstream issues, and sadly not anything Homebrew can do a huge amount to workaround.

The issue fundamentally is that npm update -g was implemented by the npm devs with one function in mind, and most users took it as a way to just update only the packages you explicitly installed or to update npm itself, and when people started using it in that way suddenly npm upstream was flooded with questions about why everything was breaking and finally it was accepted that basically nobody actually agrees on what the heck npm update -g is supposed to be doing, and something needed to be done to fix that, which led to this issue upstream.

How about just slightly rephrasing the caveat? Simply to make users feel a bit more at ease, making it a tad more obvious that we’re talking about a recommended (upstream-endorsed) thing, nothing more?

Perfectly happy with this suggestion, and for someone to correct my clumsy update/upgrade mix-up 😉. Your new commit LGTM 👍, Thanks for noticing this and going out of your way to fix it. I appreciate the heck out of someone else helping keep an eye on the Node formula 😸

[MikeMcQuaid]

Thanks @claui, @DomT4. Exciting seeing you work this out. Open-source in action ❤️

[texastoland]

Was just trying to figure out whether I should still be using --without-npm. I wish this discussion were more accessible when for others encountering into the issue. Great work all!

[DomT4]

@dnalot You should be safe to install with a Homebrewed npm these days. A lot of the kinks were ironed out during the last 6 months of 2014. The formula essentially ended up being rewritten for stability and the amount of issues we see regarding npm is almost zero these days 🎉 🎈 🍰.

Feel free to open an issue if you hit any problems :).

[texastoland]

Just finished reading the issue you linked. Thanks a ton @DomT4 🎆