e-backmark-ericsson
commented
2 years ago Sorry for raising this concern now, I'm either forgetting some good argumentation we've had or I've understood the consequences of this change too late.
With this solution we still need to create new files for a new version of each event. I do believe the reason for having individual json schemas for all historical event version stored in the repo was to make it easy to reference those schemas for all historical versions through one single branch of the repo. Now that we move from having the json schemas as the source of truth, and instead generate them for each new release (or each new version of the events?), do we still need this or could we let the yaml files be the same and change them for each new version instead? It would make reviewing of protocol changes so much easier if we don't create a new file for each new version.
magnusbaeck
z-sztrom
Applicable Issues
Fixes #282
Description of the Change
A new schema definition format that's a superset of the normal JSON schema format is introduced and all existing schemas and documentation files are merged into files in this new file format, stored in the "definitions" directory.
At the same time, the definitions of the meta member and event links are extracted to their own definition files and referenced from the event files. This both allows reuse but also makes it trivial for scripts like SDK generators to understand the structure better. Since both meta and links have evolved over time we've reconstructed different versions of those subschemas.
The schema files aren't affected at all by these changes, i.e. running generate_schemas.py on a definition file will produce a byte-identical schema file. This isn't quite true for the .md documentation; some minor changes are introduced:
To make sure the definition files don't diverge from the generated files we have an additional job in the GitHub Actions workflow that's run for all pushes and PRs. It runs the generation scripts and verifies that we won't get any dirty files in the workspace and no untracked files. See https://github.com/magnusbaeck/eiffel/actions/runs/3007678382 and https://github.com/magnusbaeck/eiffel/actions/runs/3007462169 for examples of what violations look like.
Alternate Designs
A few other options were discussed in the associated issue.
Benefits
The current representation of event schemas and documentation is an obstacle for protocol maintainers and others who want to process the information with a program. Making this change would greatly improve the situation.
Possible Drawbacks
None, I think.
Sign-off
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
Signed-off-by: Magnus Bäck \magnus.back@axis.com