Add versioning details to spec and primer

[afrittoli]

Add details about the specification versioning, the
event versioning and the schemas. Update the spec version
to 0.1.0-draft as starting in-progress version.

Update vocabulary and examples

Fixes #43

Signed-off-by: Andrea Frittoli andrea.frittoli@gmail.com

[e-backmark-ericsson]

I miss some reasoning in the proposed versioning section in the primer about why the individual event versions don't need to include the patch level on their semantic versions. Is there such a reasoning that could be documented?

As a reference, in Eiffel we do use version stepping on patch level, when for example a valid list of characters for a string value in an event is decreased, as can be seen in this document: https://github.com/eiffel-community/eiffel/blob/master/eiffel-syntax-and-usage/versioning.md#rules-for-patch-minor-and-major-versions

Maybe that is unnecessarily complex and we could use minor version stepping in such cases as well, but I believe some kind of reasoning would be valuable to provide in the primer for that.

[afrittoli]

I miss some reasoning in the proposed versioning section in the primer about why the individual event versions don't need to include the patch level on their semantic versions. Is there such a reasoning that could be documented?

As a reference, in Eiffel we do use version stepping on patch level, when for example a valid list of characters for a string value in an event is decreased, as can be seen in this document: https://github.com/eiffel-community/eiffel/blob/master/eiffel-syntax-and-usage/versioning.md#rules-for-patch-minor-and-major-versions

Maybe that is unnecessarily complex and we could use minor version stepping in such cases as well, but I believe some kind of reasoning would be valuable to provide in the primer for that.

Oh, interesting, I didn't include patch level because I didn't see a use case for that, but even if that were true it is still worth commenting about it in the spec as you mentioned.

I imagined patch level would be used for things like addressing security issues which need to be back-ported, fixing regression issues, and at first sight it didn't seem applicable to events, but perhaps it is.

[afrittoli]

Thanks for sharing the Eiffel docs about this @e-backmark-ericsson. Looking at the description of "patch":

patch: The patch version is incremented for changes that do not affect event structure, do not carry semantic significance and do not introduce additional legal values. To exemplify, narrowing a string pattern in a schema (e.g. from [a-zA-Z_] to [a-zA-Z]) would require the patch version to be stepped.

The example provided seems like a backward incompatible change to me, as existing valid producers might stop working.
Do you have a different example of what a patch version could include?

[afrittoli]

Update from the chat on slack, from Emil

It depends on whether you look at an event from producer or from consumer perspective I guess. From consumer perspective, narrowing a string schema shouldn't affect the consumer at all. Adding a new parameter to an existing json object in the event though could affect the consumer, depending on how it is implemented, as the schemas says that no additional properties are not allowed in the json objects. So, your comment on versioning in the primer saying 'as long as it ignores extra fields' is important here. Depending on language, it might be more efficient to implement the consumer in a way that it does not ignore extra fields, and thus it should be concerned about increments on the minor version, but could neglect increments on the patch version (if we add patch version numbering).

[afrittoli]

@e-backmark-ericsson Updated based on your feedback - I added the patch version for events.

[e-backmark-ericsson]

A minor (patch) correction needed.