proposal: version the diagnostic reports

[boneskull]

It'd be helpful to consumers of diagnostic reports (process.report) if the JSON output had a version identifier. I can't envision the format staying static forever, and checking Node.js versions to determine what format the report is in would be painful.

Would anyone support this idea?

[cjihrig]

I assume this is because you're building tooling that consumes the report? I'm +1 to that idea.

[eugeneo]

IMHO, this can be added later, when there is actually a need for it and you would have more context then (e.g. will understand better what should go into bumping the version, do you need minor version, etc). For now, simply treat all "unversioned" reports as having version 1.0.

[sam-github]

Seems reasonable. The report has the node version in it, so that, I think, can be used to identify format, but node-report is also a standalone module, in which case its report output is independent of the node version.

You thinking a semver version spec, or more like the NAPI version, or node ABI version, just a single incrementing integer?

/cc @richardlau & @mhdawson

[gireeshpunathil]

+1. I like major-minor semantics too. Major, if the report undergoes structural changes (sections added / removed) and minor, if keys changed.

[sam-github]

In terms of introducing the version on the next change, that sounds reasonable, except I think formats floating around right now already have multiple formats, so can't be assumed to be v1.0? Starting putting a version 1.0 right now would still leave yesterday's identical format reports as not having a known version, and a year ago's format would be indistringuishable from yesterday's, too. Not sure if that is fixable, though.

[richardlau]

Seems reasonable. The report has the node version in it, so that, I think, can be used to identify format, but node-report is also a standalone module, in which case its report output is independent of the node version.

You thinking a semver version spec, or more like the NAPI version, or node ABI version, just a single incrementing integer?

/cc @richardlau & @mhdawson

Just to clarify some history, the format of the standalone module is very different (it's meant to be read by humans) to what ended up in core (where json is output).

[richardlau]

There was an issue somewhere about taking diagnostics report out of experimental to which this proposal could be added.

[cjihrig]

There was an issue somewhere about taking diagnostics report out of experimental to which this proposal could be added.

nodejs/node#26293

[boneskull]

@cjihrig Yes, for tooling. JSON is for machines. 😉

I imagine a lone ("major") number would be sufficient. This is certainly less effort to parse than major.minor or major.minor.patch. But if there's a use case for versioning a data format in this manner, please enlighten me!

@sam-github Any report w/o a version number can be assumed to be v1, I suppose.

[boneskull]

Also, if/when we change the format, maintaining a JSON schema would be helpful. We can cross that bridge later though.

[mhdawson]

I think adding a version number is a good idea and should likely be done before report exits experimental.

[mmarchini]

Version was added in nodejs/node#28121. Closing, feel free to reopen if there's anything left to be discussed here.