flag/deprecate `global` - recommend `globalThis`

[jimmywarting]

Affected URL(s)

https://nodejs.org/dist/latest-v20.x/docs/api/globals.html#global

Description of the problem

global should really not be used anymore... it's too nodejs specific. and should be marked as legacy
globalThis works everywhere and is the "preferred" way for cross compatibility

[bnoordhuis]

Pull request welcome.

• doc deprecation: ok
• runtime warning: not ok (for now but maybe never)

[jimmywarting]

wasn't really counting on making runtime warning and having a getter method that warns ppl.
Just want it to land some @deprecated - use globalThis instead type definition somewhere.

[anonrig]

I'm ok with doc deprecation as well.

[AnandShiva]

I am interested on fixing this issue. Should the doc consider Stability index also, and mark that as
Stability: 3 - Legacy ? @jimmywarting .

[jimmywarting]

Should the doc consider Stability index also, and mark that as Stability: 3 - Legacy ?

better to ask someone else.

[Mesteery]

I am interested on fixing this issue. Should the doc consider Stability index also, and mark that as Stability: 3 - Legacy ?

I think you can write something like this Stability: 0 - Deprecated: Use `globalThis` instead.

[tniessen]

Legacy seems more appropriate than a deprecation given that it isn't causing any problems and the fact that we might never be able to remove global. (Besides, I'm not aware of a good reason for trying to do so.)

[jimmywarting]

@tniessen a doc deprecation dose not mean that we would remove it or dispatch some runtime warning for using it.
we have other deprecated things in NodeJS that will never go away b/c they are exposed for public use.

As other have put it

@bnoordhuis

• doc deprecation: ok
• runtime warning: not ok (for now but maybe never)

@anonrig
I'm ok with doc deprecation as well.

@Mesteery
I think you can write something like this Stability: 0 - Deprecated: Use `globalThis` instead.

I'm okey with doc deprecation as well.

[tniessen]

a doc deprecation dose not mean that we would remove it or dispatch some runtime warning for using it.
we have other deprecated things in NodeJS that will never go away b/c they are exposed for public use.

@jimmywarting I am familiar with our history of deprecations, which is how I know that some doc-only deprecations have had virtually zero benefits while causing a significant amount of friction.

But ignoring the past, I based my opinion on the Node.js documentation, which says:

Deprecated: The feature may emit warnings. Backward compatibility is not guaranteed.

Legacy: Although this feature is unlikely to be removed and is still covered by semantic versioning guarantees, it is no longer actively maintained, and other alternatives are available.

Based on these definitions, I personally believe that legacy better matches your concerns related to global. Whether @bnoordhuis, @anonrig, and @Mesteery find a doc-only deprecation acceptable is unrelated to my comment.