GeezerVison

However it's removal was requested in #53078 (comment) (since this is not something users should generally rely on), but the documentation wasn't fully removed from the PR before it landed.

The docs are pretty much the usage at runtime and what is does (the idea behind documenting stuff), which is inherit from V8. I did not introduced the flag per se, I just added it to the CLI available options, I don't think we should remove the documentation, when the documentation is just showing the usage and that it is part of the available CLI options.

I don't think it is the right thing to do, each flag should be documented; but feel free to land this; I'm not blocking anything.

However it's removal was requested in #53078 (comment) (since this is not something users should generally rely on), but the documentation wasn't fully removed from the PR before it landed.

The docs are pretty much the usage at runtime and what is does (the idea behind documenting stuff), which is inherit from V8. I did not introduced the flag per se, I just added it to the CLI available options, I don't think we should remove the documentation, when the documentation is just showing the usage and that it is part of the available CLI options.

I don't think it is the right thing to do, each flag should be documented; but feel free to land this; I'm not blocking anything.

Hey @juanarbol 🙂

Thanks a lot for chipping in 🙏

I see your point but I also see that we have various v8 flags that are not documented (and some that are) so I do believe that there's unclarity on this 🤔

I think that ideally we should only document the flags that node specifically implements, the V8 flags that it supports should be just listed (as they are here: available v8 options)

And the nodejs docs should simply then refer to the the V8 official documentation regarding the flags that it supports...

The problem being that I can't seem to find any official V8 documentation regarding the supported flags... any idea if there is one? 🫤

The V8 team is not that good documenting flags as well. From my personal experience, I just have to look at this file https://github.com/v8/v8/blob/b5b7de9cc158c9d4dc038841e5935c49e4764d7e/src/flags/flag-definitions.h#L2594

Again, this is not a blocker, but I don't see this adding any actual value but making things a bit more confusing. I know Node.js has a mess w/ node options and CLI options, but removing docs is not the answer IMHO.

However it's removal was requested in #53078 (comment) (since this is not something users should generally rely on), but the documentation wasn't fully removed from the PR before it landed.

The requested removal of the docs was something about V8 I wrote about. Not the CLI entry and usage.

The V8 team is not that good documenting flags as well. From my personal experience, I just have to look at this file https://github.com/v8/v8/blob/b5b7de9cc158c9d4dc038841e5935c49e4764d7e/src/flags/flag-definitions.h#L2594

I see, that's a useful link to know about, thank you very much 🙏

Again, this is not a blocker, but I don't see this adding any actual value but making things a bit more confusing. I know Node.js has a mess w/ node options and CLI options, but removing docs is not the answer IMHO.

Thanks a lot, I really appreciate the input 🙂 , personally I see the argument both ways, if we think that this is a foot gun and not something people should be using then it makes sense to me that we don't publicly document it, on the other hand if it is something that node provides it does make sense to document that...

I would have hoped for more people to chip in here 😅 , hopefully someone else will tipping the scale in either direction 🤞

Should we move it to https://nodejs.org/api/cli.html#useful-v8-options?

I think moving it to the useful V8 options section would be the right move - it's not up to Node.js to decide how it behaves, so it shouldn't be documented like other Node.js options.

FWIW the existing documentation is somewhat misleading - it would make you think that this triggers a blocking GC that's supposed to clean up all remaining unreachable objects, but that's not the case and even has been the cause of some of our flakes. That function only triggers one GC, and one single GC does not guarantee to clean up everything especially when there are weak references or ephemeron pairs in the graph.

+1 on Joyee's suggestion

Commit needs to be signed in order to land

✖  0:0      Commit must have a "Signed-off-by" trailer signed-off-by

@dario-piotrowicz Can you sign the commit by running git commit -s --amend --no-edit?
And then run git push --force-with-lease to push it.

Landed in a8350ac