ack! This contains a commit from #252

We couldn't really use the --expose-internals method, even if we wanted to. We are often running api-docs-tooling on a different Node.js version than we are generating the documentation for.

@nodejs/config to verify this schema

Im not sure I understand the goal of this PR, the schema needs to be generated by the node.js version for which the schema is meant

Im not sure I understand the goal of this PR, the schema needs to be generated by the node.js version for which the schema is meant

This PR aims to migrate schema generation into the api-docs-tooling generators. This allows the schema to be generated using different Node.js versions, similar to how documentation generation is handled.

As demonstrated in this PR, the schema can be generated using a different Node.js version, as long as the files can be parsed.

FWIW https://github.com/nodejs/node/blob/main/test/parallel/test-cli-node-options-docs.js#L20

@marco-ippolito The internal API requires that the schema to be generated using the same Node.js version it’s intended for.

Ideally, this generator should support generating schemas with previous versions—specifically the LTS versions used in CI.

Do you have an alternative method you recommend?

Whats wrong with the current way of generating the schema? It seems to be working fine

Whats wrong with the current way of generating the schema? It seems to be working fine

There's nothing "wrong" with it, however, the schema must be generated by the same version of Node.js that it is being generated for, which isn't consistent with the rest of api-doc-tooling, which intends to build similar things (i.e. Documentation, Man-page) using LTS versions of Node.js, so they can be run in the CI environment on stable versions.

Whats wrong with the current way of generating the schema? It seems to be working fine

There's nothing "wrong" with it, however, the schema must be generated by the same version of Node.js that it is being generated for, which isn't consistent with the rest of api-doc-tooling, which intends to build similar things (i.e. Documentation, Man-page) using LTS versions of Node.js, so they can be run in the CI environment on stable versions.

The schema is generated at release time just like api docs. Id rather have this costraint than regex parse a .cc file

Whats wrong with the current way of generating the schema? It seems to be working fine

There's nothing "wrong" with it, however, the schema must be generated by the same version of Node.js that it is being generated for, which isn't consistent with the rest of api-doc-tooling, which intends to build similar things (i.e. Documentation, Man-page) using LTS versions of Node.js, so they can be run in the CI environment on stable versions.

The schema is generated at release time just like api docs. Id rather have this costraint than regex parse a .cc file

I respectfully disagree, @marco-ippolito. The new API documentation tooling allows you to use it with different versions of Node.js, independent of specific Node source code. If we want to generate node.config.json for older versions, it makes sense to support this feature. I don't see any valid reason for not implementing it.

Additionally, your block has no authority over this repository. Could you please elaborate on your statement concerning "Regexing on a .cc file is not a good idea; I don’t see the benefit." We already use regex on source files for various features in the API documentation tooling generation, so I’m unclear about why you oppose this particular case in both the old and new tooling.

Additionally, your block has no authority over this repository.

This repository falls under Web Infra governance; therefore, a Core Collaborator block does not apply here. Although I do believe consensus seeking should be key here.

this is new to me, since when I am not authorized to block a PR as a collaborator @nodejs/tsc ?

Since I created the node.config.json I think I should have a saying, I don't think regex parsing the node_options.cc file is a good idea to create the schema since there are some caveats with allowed flags (we dont allow v8 flags and no-ops). The "we have been doing this already" argument doesn't seem right, I created an internal API specifically for this purpose.
I oppose to this specific use case I don't care about the old usage.

@ovflowd can you point to me to the doc saying I cannot block a PR in the doc tooling repo?
Also I noticed you removed my block without discussing it first. This feels to me disrespectful and incorrect

if you still have concerns, you can either block the upstream PR on nodejs/node or block this PR as a TSC member

Marco is a TSC member, so based on your words, it's okay for him to block this PR.

It is my understanding that repositories within different working groups and teams operate under their own governance policies. I could be mistaken, but this is my interpretation.

So this group policy is that a collaborator review can be dismissed without discussion?
That doesnt seem a good policy and its definitely not written anywhere

However, could you elaborate on your point about using regex to parse the node_options.cc file to create the schema? Especially "considering there are certain caveats with the allowed flags. For instance, we don't permit V8 flags or no-ops."

You could have asked me to elaborate more but you went ahead and removed my review

I have no interest in interacting with this PR anymore, since its clear my opinion is not respected.

It is my understanding that repositories within different working groups and teams operate under their own governance policies. I could be mistaken, but this is my interpretation.

That is true for Working Groups but not teams.

It is my understanding that repositories within different working groups and teams operate under their own governance policies. I could be mistaken, but this is my interpretation.

That is true for Working Groups but not teams.

Noted! Apologies, again @marco-ippolito, as my actions seem to have been misplaced. I understand you don't want to interact with this PR anymore, but as we are sunsetting the existing api-doc-tooling, we need some guidance on how to proceed with the node.config generation. Would you be so kind to guide us here?

My 2 cents on the objection dismissal.

First of all, Claudio, let me clarify I totally believe in good faith.
But I think you rushed a little bit (and this is coming from a professional rusher :)).

Whether Marco was or was not a TSC member was not the point, but rather than I also felt like his opinion was totally ignored with the dismissal. Being a TSC doesn't make his opinion more or less important. It's just about the person.

My (unsolicited) advice for the next time is eventually pointing out in a comment that the objection might not have been binding according to the rules. Then, after thoroughly have gone for consensus seeking as we usually do, eventually override the objection and move on with the PR.

@avivkeller should we maybe close this PR and opt-in for a very simple generator that simply imports https://github.com/nodejs/node/blob/2244a0977451c16e7cade9f1aeb46e1c136669bb/tools/doc/generate-json-schema.mjs#L4 and generates it?

I worry that there might be an alternative here without necessarily exposing Node internals, or if the generation of this file should be handled elsewhere? Any guidance would be super helpful!

Hey folks 👋 I've chatted with @marco-ippolito and we reached on the following:

1. The node.config.json schema should not be part of the API dos tooling, as it is not a "doc" per see but more of a machine-readable JSON schema for places such as IDEs
2. Ill open a PR against nodejs/node to move this generator to the root of tools
3. Ill open another PR to move the dest file to be directly within the /dist (release assets) of the output of node's build. (cc @flakey5 do we need to update anything for this file to be uploaded to worker and what not?)
4. @flakey5 we'll might need to do a redirect on the worker for /docs/xxx/node.config.json to /dist/xxx/node.config.json
5. @marco-ippolito or someone else to open a PR on nodejs/node to make the API public instead of internal.

@avivkeller how do you feel with this? Does it sound like a good path to proceed?

Sounds good to me! If relevant, you may also want to close/update #216 with the additional information

@flakey5 do we need to update anything for this file to be uploaded to worker and what not

For uploading it to nodejs/release/vX.X.X/? I don't think there would be anything except changing the actual output location for the file here https://github.com/nodejs/node/blob/102d8cff66550777bec7b0a750ae2203007f3749/Makefile#L812, definitely could be wrong though