Introducing an explicit protocol versioning scheme. (#65)

eiffel-community · Sep 6, 2016 · 99751a3 · 99751a3
1 parent acc6380
commit 99751a3
Show file tree

Hide file tree

Showing 51 changed files with 183 additions and 81 deletions.
diff --git a/README.md b/README.md
@@ -14,6 +14,7 @@ __IMPORTANT NOTICE:__ The contents of this repository currectly reflect a __DRAF
    1. [Event Structure](./eiffel-syntax-and-usage/event-structure.md)
    1. [The Meta Object](./eiffel-syntax-and-usage/the-meta-object.md)
    1. [The Links Object](./eiffel-syntax-and-usage/the-links-object.md)
+   1. [Versioning](./eiffel-syntax-and-usage/versioning.md)
    1. [Compositions and Validity Checking](./eiffel-syntax-and-usage/compositions-and-validity-checking.md)
 1. The Eiffel Vocabulary
    1. [EiffelActivityTriggeredEvent](./eiffel-vocabulary/EiffelActivityTriggeredEvent.md)

diff --git a/eiffel-syntax-and-usage/the-meta-object.md b/eiffel-syntax-and-usage/the-meta-object.md
@@ -16,9 +16,9 @@ __Description:__ The type of event. This field is required by the recipient of t
 
 ### meta.version
 __Type:__ String  
-__Format:__ Semantic version excluding PATCH.  
+__Format:__ [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html)  
 __Required:__ Yes  
-__Description:__ The version of the event type. This field is required by the recipient of the event to interpret the contents.
+__Description:__ The version of the event type. This field is required by the recipient of the event to interpret the contents. Please see [Versioning](./versioning.md) for more information.
 
 ### meta.time
 __Type:__ Integer  

diff --git a/eiffel-syntax-and-usage/versioning.md b/eiffel-syntax-and-usage/versioning.md
@@ -0,0 +1,13 @@
+# Versioning
+In Eiffel, each individual event type is versioned independently. This version is declared by the __meta.version__ property (see [The Meta Object](./the-meta-object.md)) and follows the [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html) format. The documentation of each event type lists the complete version history of that type, including links to commits introducing older versions of the type.
+
+The independent versioning of event types, as opposed to a protocol-wide versioning scheme, was chosen for the greater flexibility and extensibility it affords. There are consequences, however, which are important to understand:
+* Consumers must always be ready to receive event types which they are unable to parse: the event producer may be ahead of the consumer on one event type, but not another. Similarly, new and/or custom event types must be expected and handled.
+* Backwards incompatible changes may not be introduced to the __meta.type__ and __meta.version__ properties, as these together form the key which allows the consumer to unlock the remainder of the event.
+
+That being said, to facilitate compatibility and consistency, the Eiffel protocol as described in this repository is released in named and internally coherent _editions_. Each of these editions is represented as a GitHub [release](https://github.com/Ericsson/eiffel/releases). A history of Eiffel editions is available below.
+
+| Edition   | Tag |
+| --------- | ------------------ |
+| Bordeaux  | _First edition. Not yet finished. Planned for end of [Drop 4](https://github.com/Ericsson/eiffel/milestone/4)._  |
+
diff --git a/eiffel-vocabulary/EiffelActivityCanceledEvent.md b/eiffel-vocabulary/EiffelActivityCanceledEvent.md
@@ -7,5 +7,10 @@ __Type:__ String
 __Required:__ No  
 __Description:__ Any human readable information as to the reason for dequeueing.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelActivityCanceledEvent/simple.json)
diff --git a/eiffel-vocabulary/EiffelActivityFinishedEvent.md b/eiffel-vocabulary/EiffelActivityFinishedEvent.md
@@ -39,5 +39,10 @@ __Type:__ String
 __Required:__ Yes  
 __Description:__ The URI at which the log can be retrieved.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelActivityFinishedEvent/simple.json)
diff --git a/eiffel-vocabulary/EiffelActivityStartedEvent.md b/eiffel-vocabulary/EiffelActivityStartedEvent.md
@@ -22,5 +22,10 @@ __Type:__ String
 __Required:__ Yes  
 __Description:__ The URI at which the log can be retrieved.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelActivityStartedEvent/simple.json)
diff --git a/eiffel-vocabulary/EiffelActivityTriggeredEvent.md b/eiffel-vocabulary/EiffelActivityTriggeredEvent.md
@@ -41,6 +41,11 @@ __Required:__ No
 __Legal values:__ MANUAL, SEMI_AUTOMATED, AUTOMATED, OTHER  
 __Description:__ The type of execution (often related to, but ultimately separate from, __data.trigger.type__).
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelActivityTriggeredEvent/simple.json)
 * [Example containing custom data](../examples/events/EiffelActivityTriggeredEvent/simple-customdata.json)
diff --git a/eiffel-vocabulary/EiffelArtifactCreatedEvent.md b/eiffel-vocabulary/EiffelArtifactCreatedEvent.md
@@ -92,6 +92,11 @@ __Type:__ String
 __Required:__ Yes  
 __Description:__ The version of the dependency. Note that [version range notation](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) is supported.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelArtifactCreatedEvent/simple.json)
 * [Interface example](../examples/events/EiffelArtifactCreatedEvent/interface.json)

diff --git a/eiffel-vocabulary/EiffelArtifactPublishedEvent.md b/eiffel-vocabulary/EiffelArtifactPublishedEvent.md
@@ -22,5 +22,10 @@ __Type:__ String
 __Required:__ Yes  
 __Description:__ The URI at which the artifact can be retrieved.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelArtifactPublishedEvent/simple.json)
diff --git a/eiffel-vocabulary/EiffelCompositionDefinedEvent.md b/eiffel-vocabulary/EiffelCompositionDefinedEvent.md
@@ -12,5 +12,10 @@ __Type:__ String
 __Required:__ No  
 __Description:__ The version of the composition, if any. This is in a sense redundant, as relationships between compositions can be tracked via the __PREVIOUS_VERSION__ link type, but can be used for improved clarity and semantics.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelCompositionDefinedEvent/simple.json)
diff --git a/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md b/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md
@@ -43,5 +43,10 @@ __Type:__ String
 __Required:__ No  
 __Description:__ Any group, such as a development team, committee or test group, to which the issuer belongs.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelConfidenceLevelModifiedEvent/simple.json)
diff --git a/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md b/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md
@@ -39,6 +39,11 @@ __Type:__ String
 __Required:__ No  
 __Description:__ A URI identifying the environment description. This is the catch-all method of environment descriptions. Eiffel does not concern itself with the format or nature of the description, but merely points to its location.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [URI example](../examples/events/EiffelEnvironmentDefinedEvent/uri.json)
 * [Host example](../examples/events/EiffelEnvironmentDefinedEvent/host.json)

diff --git a/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md b/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md
@@ -29,5 +29,10 @@ __Type:__ String
 __Required:__ No  
 __Description:__ A version context which other events can relate to. This member SHOULD be used in tandem with one of the other optional members - a version by itself is not very informative.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelFlowContextDefinedEvent/simple.json)
diff --git a/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md b/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md
@@ -191,5 +191,11 @@ __Type:__ String
 __Required:__ Yes  
 __Description:__ The URI of the repo.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
-* [Simple example](../examples/events/EiffelSourceChangeCreatedEvent/simple.json)
+* [Simple example](../examples/events/EiffelSourceChangeCreatedEvent/simple.json)
+
diff --git a/eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md b/eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md
@@ -126,5 +126,10 @@ __Type:__ String
 __Required:__ Yes  
 __Description:__ The URI of the repo.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelSourceChangeSubmittedEvent/simple.json)
diff --git a/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md b/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md
@@ -51,5 +51,10 @@ __Type:__ String
 __Required:__ Yes  
 __Description:__ The URI at which the log can be retrieved.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelTestCaseFinishedEvent/simple.json)
diff --git a/eiffel-vocabulary/EiffelTestCaseStartedEvent.md b/eiffel-vocabulary/EiffelTestCaseStartedEvent.md
@@ -63,5 +63,10 @@ __Type:__ String
 __Required:__ Yes  
 __Description:__ The URI at which the log can be retrieved.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelTestCaseStartedEvent/simple.json)
diff --git a/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md b/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md
@@ -49,5 +49,10 @@ __Type:__ String
 __Required:__ Yes  
 __Description:__ The URI at which the log can be retrieved.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelTestSuiteFinishedEvent/simple.json)
diff --git a/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md b/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md
@@ -35,5 +35,10 @@ __Type:__ String
 __Required:__ Yes  
 __Description:__ The URI at which the log can be retrieved.
 
+## Version History
+| Version   | Introducing Commit |
+| --------- | ------------------ |
+| 1.0.0     | _Current version_  |
+
 ## Examples
 * [Simple example](../examples/events/EiffelTestSuiteStartedEvent/simple.json)
diff --git a/examples/events/EiffelActivityCanceledEvent/simple.json b/examples/events/EiffelActivityCanceledEvent/simple.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelActivityCanceledEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0",
     "source": {

diff --git a/examples/events/EiffelActivityFinishedEvent/simple.json b/examples/events/EiffelActivityFinishedEvent/simple.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelActivityFinishedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0",
     "source": {

diff --git a/examples/events/EiffelActivityStartedEvent/simple.json b/examples/events/EiffelActivityStartedEvent/simple.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelActivityStartedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0",
     "source": {

diff --git a/examples/events/EiffelActivityTriggeredEvent/simple-customdata.json b/examples/events/EiffelActivityTriggeredEvent/simple-customdata.json
@@ -2,7 +2,7 @@
   "meta": {
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0",
     "type": "EiffelActivityTriggeredEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "source": {
       "domainId": "test-domainId"

diff --git a/examples/events/EiffelActivityTriggeredEvent/simple.json b/examples/events/EiffelActivityTriggeredEvent/simple.json
@@ -2,7 +2,7 @@
   "meta": {
     "id": "e1e93f13-7c3c-4f17-9753-ebf0c86ff1c2",
     "type": "EiffelActivityTriggeredEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "source": {
       "domainId": "example.domain"

diff --git a/examples/events/EiffelArtifactCreatedEvent/backend.json b/examples/events/EiffelArtifactCreatedEvent/backend.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelArtifactCreatedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "source": {
       "domainId": "example.domain"

diff --git a/examples/events/EiffelArtifactCreatedEvent/dependent.json b/examples/events/EiffelArtifactCreatedEvent/dependent.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelArtifactCreatedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "source": {
       "domainId": "example.domain"

diff --git a/examples/events/EiffelArtifactCreatedEvent/interface.json b/examples/events/EiffelArtifactCreatedEvent/interface.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelArtifactCreatedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "source": {
       "domainId": "example.domain"

diff --git a/examples/events/EiffelArtifactCreatedEvent/simple.json b/examples/events/EiffelArtifactCreatedEvent/simple.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelArtifactCreatedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0",
     "source": {

diff --git a/examples/events/EiffelArtifactPublishedEvent/simple.json b/examples/events/EiffelArtifactPublishedEvent/simple.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelArtifactPublishedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0",
     "source": {

diff --git a/examples/events/EiffelCompositionDefinedEvent/simple.json b/examples/events/EiffelCompositionDefinedEvent/simple.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelCompositionDefinedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "domainId": "example.domain",
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0"

diff --git a/examples/events/EiffelConfidenceLevelModifiedEvent/simple.json b/examples/events/EiffelConfidenceLevelModifiedEvent/simple.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelConfidenceLevelModifiedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0",
     "source": {

diff --git a/examples/events/EiffelEnvironmentDefinedEvent/host.json b/examples/events/EiffelEnvironmentDefinedEvent/host.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelEnvironmentDefinedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0",
     "source": {

diff --git a/examples/events/EiffelEnvironmentDefinedEvent/image.json b/examples/events/EiffelEnvironmentDefinedEvent/image.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelEnvironmentDefinedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0",
     "source": {

diff --git a/examples/events/EiffelEnvironmentDefinedEvent/uri.json b/examples/events/EiffelEnvironmentDefinedEvent/uri.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelEnvironmentDefinedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0",
     "source": {

diff --git a/examples/events/EiffelFlowContextDefinedEvent/simple.json b/examples/events/EiffelFlowContextDefinedEvent/simple.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelFlowContextDefined",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "source": {
       "domainId": "example.domain"

diff --git a/examples/events/EiffelSourceChangeCreatedEvent/simple.json b/examples/events/EiffelSourceChangeCreatedEvent/simple.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelSourceChangeCreatedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "domainId": "example.domain",
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0"

diff --git a/examples/events/EiffelSourceChangeSubmittedEvent/simple.json b/examples/events/EiffelSourceChangeSubmittedEvent/simple.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelSourceChangeSubmittedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "domainId": "example.domain",
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0"

diff --git a/examples/events/EiffelTestCaseFinishedEvent/simple.json b/examples/events/EiffelTestCaseFinishedEvent/simple.json
@@ -1,7 +1,7 @@
 {
   "meta": {
     "type": "EiffelTestCaseFinishedEvent",
-    "version": "1.0",
+    "version": "1.0.0",
     "time": 1234567890,
     "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0",
     "source": {