Add support for experimental event versions

[magnusbaeck]

Applicable Issues

Fixes #335

Description of the Change

Adding a section to versioning.md that describes that experimental 0.x.y versions are allowed and how they're supposed to be used. The template file for the documentation Markdown files is updated to include a cautionary banner for 0.x.y. versions. Finally, the YAML schema is updated to include an "experimental" flag for link types that (only) point to experimental events.

I've made an example commit on the exp-demo branch so you can see how an experimental event (and links to it) are rendered.

Alternate Designs

None.

Benefits

We've seen a need to introduce event types before we're 100% certain how they're supposed to work, and using experimental events for this would avoid calcifying bad designs.

Possible Drawbacks

This complicates the protocol specification and makes life harder for generated SDKs.

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]

With the current proposal all source events that link to an experimental event needs to be updated when the experimental event becomes non-experimental. Until now we have never needed to update any source event types just because their target event types change. Is this a behavior we'd like to introduce? I don't have a good alternative solution though.

[magnusbaeck]

We'd be updating the documentation of a source event in a way that doesn't affect the schema nor any semantic aspects of the event. It's an helpful hint to the emitter of a source event. I'd consider this similar to typo correction, i.e. something we can change in existing YAML files without issuing any new versions.

[e-backmark-ericsson]

We'd be updating the documentation of a source event in a way that doesn't affect the schema nor any semantic aspects of the event. It's an helpful hint to the emitter of a source event. I'd consider this similar to typo correction, i.e. something we can change in existing YAML files without issuing any new versions.

Fair enough. Agreed.

[m-linner-ericsson]

Was wondering if we want to point out in the link warning text that the link might be removed without stepping the major version. Otherwise we could just point to the longer versioning text for details.

If we don't want to this is approved.