doc: mark global object as legacy

[mertcanaltin]

doc: mark global object as legacy

Fixes: #47784

[benjamingr]

The global object is Node.js specific and considered legacy.

Considered legacy by whom?

[mertcanaltin]

The global object is Node.js specific and considered legacy.

Considered legacy by whom?

I tried to do it based on the comments in the issue, I may be lacking in this regard, sorry @benjamingr
we thought it was a legacy and it would be good if we suggested globalThis as a suggestion 🤔

[dnalborczyk]

@benjamingr I don't know if legacy is the right therm to use, but in order to write cross-platform code, one should likely not use global anymore, and instead use globalThis.

the original proposal tried to use global, but ran into webcompat problems: https://github.com/tc39/proposal-global and subsequently renamed to globalThis.

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis#description

I think it's good to discourage developers from using it and a doc deprecation is a good thing.

[tniessen]

This is not a formal deprecation. As Ben said in #47784, we might never be able to warn about usage at runtime yet alone remove it. I am not convinced that formally deprecating this API helps.

We could mark it as legacy. Or we could just add a sentence saying that new applications should consider using globalThis for improved compatibility with other runtimes.

[mertcanaltin]

This is not a formal deprecation. As Ben said in #47784, we might never be able to warn about usage at runtime yet alone remove it. I am not convinced that formally deprecating this API helps.

We could mark it as legacy. Or we could just add a sentence saying that new applications should consider using globalThis for improved compatibility with other runtimes.

yes i will update it that way if appropriate

[jimmywarting]

I was thinking more like how all the other docs do it, take url parser for instant.

> Stability: 3 - Legacy: Use the WHATWG URL API instead.

So maybe

> Stability: 3 - Legacy. use globalThis instead.

so that it gets a little legacy label too like this

I also wouldn't mind if it where deprecated also.

[mertcanaltin]

I was thinking more like how all the other docs do it, take url parser for instant.

> Stability: 3 - Legacy: Use the WHATWG URL API instead.

So maybe

Stability: 3 - Legacy. use globalThis instead.

so that it gets a little legacy label too like this

I also wouldn't mind if it where deprecated also.

thanks for your suggestion i made an update

[tniessen]

Optional nit: the commit message is rather inaccurate. Consider changing the first commit message to something like this:

doc: mark global object as legacy

Fixes: https://github.com/nodejs/node/issues/47784

^{(Or ping me if you'd like me to do so.)}

[tniessen]

cc @nodejs/tsc for visibility

[mcollina]

lgtm

[nodejs-github-bot]

Landed in 33231b0