Add rules for patch, minor and major version increments

eiffel-syntax-and-usage/versioning.md

@@ -32,3 +32,20 @@ That being said, to facilitate compatibility and consistency, the Eiffel protoco
 | Agen  | _Reserved for future use._  | |
 | Toulouse  | [edition-toulouse](../../../tree/edition-toulouse)  | Stepped major version of TERCC. Updated FLOW_CONTEXT link type, resulting in new minor version of all event types. |
 | Bordeaux  | [edition-bordeaux](../../../tree/edition-bordeaux)  | Initial edition. |
+
+## Rules for patch, minor and major versions
+In the case of a communication protocol, applying Semantic Versioning is not as straight-forward as for a regular software implementation. The ground rule is to consider backwards compatibility from the perspective of the consumer of an event. Below are rules and examples of how this applies to the Eiffel protocol.
+
+* Mere documentation updates with no impact on event schemas require no stepping of the version at all. Indeed, the version is best understood as a _schema_ versions. Or, conversely, documentation SHALL NOT be updated in such a way as to change the semantics of event types or their properties without also making a change to the schema. To exemplify, changing the meaning of a property without changing its name or format is not allowed, as this introduces hidden compatibility issues.
+* __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.
+* __minor:__ The minor version is incremented for changes to event structure or other changes that carry semantic significance but are backwards compatible from a consumer's point of view. To exemplify, adding a property to an event type without changing the syntax of existing properties would require the minor version to be stepped. Note that existing _producers_ may not be able to produce the new event type version, but a _consumer_ SHALL be able to derive the same information as from the previous version. Note that this means that consumers SHOULD be prepared to handle (and disregard) unrecognized properties in higher minor versions than they are familiar with.
+* __major:__ The major version is incremented for changes that are not backwards compatible from the consumer's point of view. To exemplify, removing or renaming an existing property would require the minor version to be stepped. Similarly, broadening a string pattern to allow additional legal values (e.g. from `[a-zA-Z]` to `[a-zA-Z_]`) requires the major version to be stepped.
+
+## Updating Historical Event Types and Editions
+As with any software, historical versions may need to be updated occasionally. Users of a specific edition of the Eiffel protocol may require improvements or corrections, without having to migrate to the latest event type versions. Such changes are perfectly permissible: it is important to understand that the versions do not represent chronology, but compatibility. In other words, version 2.1.0 of a particular event type may well be introduced _after_ version 3.0.0. The one exception is that only the highest extant version at any given level may step that level. To exemplify:
+
+* If 2.0.0 and 3.0.0 exist, only the 3.0.0 event may serve as the baseline for a new major version (thereby stepping to 4.0.0).
+* If 2.0.0 and 2.1.0 exist, only the 2.1.0 event may serve as the baseline for a new minor version (thereby stepping to 2.2.0).
+* If 2.0.0 and 2.0.1 exist, the 2.0.0 event may serve as a baseline for new versions. Instead the 2.0.1 event shall be used as baseline for changes to the event type.
+
+Users are not bound to use only event types included in an edition. To exemplify, a consumer may accept all [edition-toulouse](../../../tree/edition-toulouse) events, plus [EiffelIssueVerifiedEvent](../eiffel-vocabulary/EiffelIssueVerifiedEvent.md) 2.0.0, which is not included in that edition. Indeed, it may also accept additional events not included at all, such as [EiffelIssueDefinedEvent](../eiffel-vocabulary/EiffelIssueDefinedEvent.md). In this sense, editions are non-exclusive. That being said, if there is a need to identify a collection of events updated from a historical edition, a new edition may be created for that purpose. The naming scheme of such editions SHALL be `<baseline edition name>-<increment integer starting at 1>`. To exemplify, an updated [edition-toulouse](../../../tree/edition-toulouse) would be named `edition-toulouse-1`, while a subsequent one would be named `edition-toulouse-2`, et cetera.