Add diff_definitions.py for diffing event definition files and schema files

[magnusbaeck]

Applicable Issues

Partial solution to #319

Description of the Change

This new script makes it easy to compare the current definitions of events and other types against a chosen base, e.g. the current state of the master branch or a previous edition. It produces diff commands that can be run to produce the wanted comparison.

Since figuring out the most recent version of each type is a pretty common operation, a new versions module is introduced for this purpose. The existing find-latest-schemas.py script has been adapted to use the new module.

A follow-up commit will add a workflow that posts a comment with the output of running the diff_definitions.py commands when someone makes a particular comment in the PR discussion. This'll make it easy for people to see the actual effects of a commit without having to download the commit and run the command locally.

Alternate Designs

None.

Benefits

Makes it quite easy to compare different versions of the protocol.

Possible Drawbacks

None, but it's notable that if we'd just keep the most current version of each type we'd be able to use normal Git commands for this diff (but we'd have other problems instead).

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 <[email protected]>

[e-backmark-ericsson]

Throughout this PR the term 'latest' is used, but it's implemented as if it was called 'highest'. We haven't had such a scenario yet, but what if we'd need to patch an old edition because some user cannot take the latest non-backwards compatible edition. Then we would step some minor/patch version of some event that could also have a higher major version stored for it. In that scenario, we would not get the 'latest' versions with this code but rather the 'highest', and we would need another means to find the latest version under a certain old major version.
Should we rename 'latest' to 'highest' throughout this PR to cater for possible future patch releases of old editions?

[magnusbaeck]

In principle I agree about saying "highest" rather than "latest" (even though I think most people would consider them synonymous in this context), but there are several existing uses of "latest" (find-latest-schemas.py and generate_manifest.py but also in a few places in the documentation). I'd prefer consistency over a slightly less ambiguous term.

[e-backmark-ericsson]

In principle I agree about saying "highest" rather than "latest" (even though I think most people would consider them synonymous in this context), but there are several existing uses of "latest" (find-latest-schemas.py and generate_manifest.py but also in a few places in the documentation). I'd prefer consistency over a slightly less ambiguous term.

I agree and I will instead eventually create a separate issue to rename 'latest' to 'highest' (or similar) all over our docs