Conversation
|
@sferik Thanks for doing this. Regarding versioned and unversioned schema files, I think the versioned files need to be primary/canonical and the 'latest' or 'current' version a convenience. I think the generated result set data file needs to contain a schema spec that includes the schema version so that it will always be usable when future schema versions are released. I may be misunderstanding though. Here is a ChatGPT discussion of their recommended version strategy and implementation: https://chatgpt.com/share/6a095730-57d0-8322-aac5-38f90035c2ac (References in that chat to 'cov-loupe' are unintentional and should be 'simplecov' instead.) |
| "groups": { "<group name>": { /* per-group stats + files */ } }, | ||
| "errors": { /* minimum_coverage, minimum_coverage_by_file, minimum_coverage_by_group, maximum_coverage_drop violations */ } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Would be nice to get full example for some minimal 'Hello World' script (that covers all features).
| gem.required_ruby_version = ">= 3.1" | ||
|
|
||
| gem.files = Dir["lib/**/*.*", "exe/*", "LICENSE", "CHANGELOG.md", "README.md", "doc/*"] | ||
| gem.files = Dir["{lib,schemas}/**/*.*", "exe/*", "LICENSE", "CHANGELOG.md", "README.md", "doc/*"] |
There was a problem hiding this comment.
While we are at it, maybe it is possible to generate human readable documentation with real world examples to close #1030 (comment) ?
There are a couple of documentation generators listed https://json-schema.org/tools#documentation but I haven't found a nice one yet.
|
@keithrbennett I’ve incorporated your feedback in 590da07. Please have another look and let me know if you have any more feedback before I merge this in. |
|
@abitrolly I’ve incorporated your feedback in dcf5e59. Please have another look and let me know if you have any more feedback before I merge this in. |
sferik
force-pushed
the
schema
branch
2 times, most recently
from
bf7b0a1 to
071579e
Compare
sferik
force-pushed
the
main
branch
2 times, most recently
from
fc484f1 to
ad30894
Compare
…yload Move the canonical schema to schemas/coverage-v1.0.schema.json with a versioned $id, so each version is immutable. Keep schemas/coverage.schema.json as a convenience alias for "the latest" that mirrors the canonical except for $id, title, and description. A new spec asserts the two stay structurally identical so the alias cannot drift. Add a top-level $schema field to every coverage.json holding the versioned canonical URL, so each emitted document is self-describing and consumers can resolve the exact contract without out-of-band knowledge. meta.schema_version stays as the human-readable companion.
Draft-07 is from 2018. 2020-12 is the current published draft, supported by every modern validator (including json_schemer in the dev Gemfile) and by every IDE that auto-resolves $schema URLs. There is no compatibility reason to ship a 2018-era contract as the public schema. Update the meta-schema URI in both schema files (the versioned canonical and the unversioned alias) and switch the spec assertion from JSONSchemer.draft7 to JSONSchemer.draft202012. Retitle the README section to "JSON Schema for coverage.json" so it is searchable for someone looking for "JSON schema simplecov" rather than for the internal filename, and tighten the opening paragraph (the second bullet was redundant with the prose that followed).
|
@sferik looks good. Copying standard when a new version is released seems like a good way to preserve backward compatibility. |
Since we want third-party tools to use the
coverage.json(and not.resultset.json), we should encourage that by versioning the document and publishing a JSON Schema. This was suggested by @keithrbennett in #1143 (comment) and I agree that it’s a good idea.This PR adds:
schemas/coverage.schema.json, which includes meta, total, per-file coverage, groups, and all four errors shapes. The gemspec has also been modified to add theschemasdirectory.meta.schema_version(currently "1.0"), which is intentionally independent of the gem version, so we can bump the gem version without bumping the schema version.JSONFormatteroutput against the schema.json_schemeras a development dependency to validate the schema.