Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

proposal: version the diagnostic reports #306

Closed
boneskull opened this issue Jun 7, 2019 · 12 comments
Closed

proposal: version the diagnostic reports #306

boneskull opened this issue Jun 7, 2019 · 12 comments

Comments

@boneskull
Copy link

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
Copy link

cjihrig commented Jun 7, 2019

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

@eugeneo
Copy link

eugeneo commented Jun 7, 2019

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
Copy link

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
Copy link
Member

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

@sam-github
Copy link

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
Copy link
Member

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
Copy link
Member

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

@cjihrig
Copy link

cjihrig commented Jun 7, 2019

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

nodejs/node#26293

@boneskull
Copy link
Author

@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
Copy link
Author

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

@mhdawson
Copy link
Member

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

@mmarchini
Copy link
Contributor

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

8 participants