Add rules for patch, minor and major version increments

[d-stahl-ericsson]

Applicable Issues

#189, #200.

Description of the Change

Added rules for patch, minor and major version increments in versioning.md, as well as handling of historical versions and editions.

Alternate Designs

There are several ways to interpret SemVer rules for the protocol - that's the point of stating them explicitly. If you believe there is a more conducive interpretation, please comment the PR :)

Benefits

Hopefully no more discussion regarding versioning every time we update an event type.

Possible Drawbacks

Can't see any drawbacks from having rules per se. This particular set of rules might have unforeseen consequences - please point them out if you can spot any.

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: Daniel Ståhl [email protected]

[e-backmark-ericsson]

I think some more clarity is needed here. As a ground rule I think the semver definitions are fine, with the addition that you should have the event consumer in mind when determining how to step the version.

1. MAJOR version when you make incompatible (from an event consumers perspective) schema changes,
2. MINOR version when you add functionality in a backwards-compatible manner (from an event consumers perspective), and
3. PATCH version when you make backwards-compatible (from an event consumers perspective) bug fixes.

With the above definitions it is still not very clear when to step what portion of the version identifier. Even though adding more examples will never be enough I guess we could sort out some misunderstandings. Added examples:

• Plain documentation updates, not affecting the event schema (such as PR Rephrased meta.time format in all event types. #194 ), need no update in the versioning at all. The event version should actually be considered an event schema version.
• Narrowing a string pattern in a schema (e.g. from [a-zA-Z_] to [a-zA-Z]) - patch
• Broadening a string pattern in a schema (e.g. from [a-zA-Z] to [a-zA-Z_]) - major (or should this be considered backwards compatible, just like an added property is in the next example?)
• Adding a property to an existing object in the event schema - minor. Maybe a note is suitable here, stating that a consumer SHOULD be prepared to handle additional properties in an event/event object?
• Renaming or removing a property in an event schema - major

For 'minor':

• Typo: 'backwards' should be 'backwards compatible'
• I guess the meaning of a property could be changed without breaking backwards compatibility, as long as the syntax is maintained (again PR Rephrased meta.time format in all event types. #194 where the meaning of the time field is slightly altered/clarified but not its syntax). Suggestion: remove 'or meaning '.

For 'major':

• I think it's clearer to state that any backwards incompatible change from a consumers point of view should be noted as a major change.

[d-stahl-ericsson]

As a ground rule I think the semver definitions are fine, with the addition that you should have the event consumer in mind when determining how to step the version. [...] it is still not very clear when to step what portion of the version identifier.

Exactly, that's the point of the PR :) SemVer in principle, but in practice it's far from clear how to actually apply it. For instance, what is a backwards compatible bug fix in this context?

Increased clarity is never a bad thing. I like your more precise examples, but I don't see how we achieve that by removing the current statements.

As for meaning - if the meaning of a property is changed that should not be considered a backwards compatible change. (On a side note, changing a property's meaning without changing syntax is a bad idea, but nevertheless.)

[e-backmark-ericsson]

removing or renaming an existing property would require the minor version to be stepped

should be 'major', right?

[d-stahl-ericsson]

Thanks! Fixed.

[e-backmark-ericsson]

the 2.0.0 event may serve

I think you mean 'the 2.0.0 event may not serve'

[d-stahl-ericsson]

Thanks! Fixed.