Add versioning details to spec and primer

cloudevents-binding.md

@@ -94,7 +94,7 @@ Full example of a CDEvents transported through a CloudEvent in HTTP *binary* mod
 POST /sink HTTP/1.1
 Host: cdevents.example.com
 ce-specversion: 1.0
-ce-type: dev.cdevents.taskrun.started
+ce-type: dev.cdevents.taskrun.started.0.1-draft
 ce-time: 2018-04-05T17:31:00Z
 ce-id: A234-1234-1234
 ce-source: /staging/tekton/
@@ -104,7 +104,7 @@ Content-Length: nnnn
 
 {
    "context": {
-      "version" : "draft",
+      "version" : "0.1.0-draft",
       "id" : "A234-1234-1234",
       "source" : "/staging/tekton/",
       "type" : "dev.cdevents.taskrun.started",

continuous-deployment-pipeline-events.md

@@ -48,7 +48,7 @@ A `service` can represent for example a binary that is running, a daemon, an app
 
 This event represents an environment that has been created. Such an environment can be used to deploy services in.
 
-- Event Type: __`dev.cdevents.environment.created`__
+- Event Type: __`dev.cdevents.environment.created.0.1-draft`__
 - Predicate: created
 - Subject: [`environment`](#environment)
 
@@ -63,7 +63,7 @@ This event represents an environment that has been created. Such an environment
 
 This event represents an environment that has been modified.
 
-- Event Type: __`dev.cdevents.environment.modified`__
+- Event Type: __`dev.cdevents.environment.modified.0.1-draft`__
 - Predicate: modified
 - Subject: [`environment`](#environment)
 
@@ -78,7 +78,7 @@ This event represents an environment that has been modified.
 
 This event represents an environment that has been deleted.```
 
-- Event Type: __`dev.cdevents.environment.deleted`__
+- Event Type: __`dev.cdevents.environment.deleted.0.1-draft`__
 - Predicate: deleted
 - Subject: [`environment`](#environment)
 
@@ -92,7 +92,7 @@ This event represents an environment that has been deleted.```
 
 This event represents a new instance of a service that has been deployed
 
-- Event Type: __`dev.cdevents.service.deployed`__
+- Event Type: __`dev.cdevents.service.deployed.0.1-draft`__
 - Predicate: deployed
 - Subject: [`service`](#service)
 
@@ -105,7 +105,7 @@ This event represents a new instance of a service that has been deployed
 
 This event represents an existing instance of a service that has been upgraded to a new version
 
-- Event Type: __`dev.cdevents.service.upgraded`__
+- Event Type: __`dev.cdevents.service.upgraded.0.1-draft`__
 - Predicate: upgraded
 - Subject: [`service`](#service)
 
@@ -118,7 +118,7 @@ This event represents an existing instance of a service that has been upgraded t
 
 This event represents an existing instance of a service that has been rolled back to a previous version
 
-- Event Type: __`dev.cdevents.service.rolledback`__
+- Event Type: __`dev.cdevents.service.rolledback.0.1-draft`__
 - Predicate: rolledback
 - Subject: [`service`](#service)
 
@@ -131,7 +131,7 @@ This event represents an existing instance of a service that has been rolled bac
 
 This event represents the removal of a previously deployed service instance and is thus not longer present in the specified environment
 
-- Event Type: __`dev.cdevents.service.removed`__
+- Event Type: __`dev.cdevents.service.removed.0.1-draft`__
 - Predicate: removed
 - Subject: [`service`](#service)
 
@@ -144,7 +144,7 @@ This event represents the removal of a previously deployed service instance and
 
 This event represents an existing instance of a service that has an accessible URL for users to interact with it. This event can be used to let other tools know that the service is ready and also available for consumption.
 
-- Event Type: __`dev.cdevents.service.published`__
+- Event Type: __`dev.cdevents.service.published.0.1-draft`__
 - Predicate: published
 - Subject: [`service`](#service)
 

continuous-integration-pipeline-events.md

@@ -72,7 +72,7 @@ An `artifact` is usually produced as output of a build process. Events need to b
 
 This event represents a Build task that has been queued; this build process usually is in charge of producing a binary from source code.
 
-- Event Type: __`dev.cdevents.build.queued`__
+- Event Type: __`dev.cdevents.build.queued.0.1.0-draft`__
 - Predicate: queued
 - Subject: [`build`](#build)
 
@@ -87,7 +87,7 @@ This event represents a Build task that has been queued; this build process usua
 
 This event represents a Build task that has been started; this build process usually is in charge of producing a binary from source code.
 
-- Event Type: __`dev.cdevents.build.started`__
+- Event Type: __`dev.cdevents.build.started.0.1.0-draft`__
 - Predicate: started
 - Subject: [`build`](#build)
 
@@ -102,7 +102,7 @@ This event represents a Build task that has been started; this build process usu
 
 This event represents a Build task that has finished. This event will eventually contain the finished status, success, error or failure
 
-- Event Type: __`dev.cdevents.build.finished`__
+- Event Type: __`dev.cdevents.build.finished.0.1.0-draft`__
 - Predicate: finished
 - Subject: [`build`](#build)
 
@@ -118,7 +118,7 @@ This event represents a Build task that has finished. This event will eventually
 
 This event represents a Test task that has been queued, and it is waiting to be started.
 
-- Event Type: __`dev.cdevents.testcase.queued`__
+- Event Type: __`dev.cdevents.testcase.queued.0.1.0-draft`__
 - Predicate: queued
 - Subject: [`testCase`](#testcase)
 
@@ -133,7 +133,7 @@ This event represents a Test task that has been queued, and it is waiting to be
 
 This event represents a Test task that has started.
 
-- Event Type: __`dev.cdevents.testcase.started`__
+- Event Type: __`dev.cdevents.testcase.started.0.1.0-draft`__
 - Predicate: started
 - Subject: [`testCase`](#testcase)
 
@@ -148,7 +148,7 @@ This event represents a Test task that has started.
 
 This event represents a Test task that has finished. This event will eventually contain the finished status: success, error or failure.
 
-- Event Type: __`dev.cdevents.testcase.finished`__
+- Event Type: __`dev.cdevents.testcase.finished.0.1.0-draft`__
 - Predicate: finished
 - Subject: [`testCase`](#testcase)
 
@@ -163,7 +163,7 @@ This event represents a Test task that has finished. This event will eventually
 
 This event represents a Test suite that has been started.
 
-- Event Type: __`dev.cdevents.testsuite.started`__
+- Event Type: __`dev.cdevents.testsuite.started.0.1.0-draft`__
 - Predicate: started
 - Subject: [`testSuite`](#testsuite)
 
@@ -178,7 +178,7 @@ This event represents a Test suite that has been started.
 
 This event represents a Test suite that has has finished, the event will contain the finished status: success, error or failure.
 
-- Event Type: __`dev.cdevents.testsuite.finished`__
+- Event Type: __`dev.cdevents.testsuite.finished.0.1.0-draft`__
 - Predicate: finished
 - Subject: [`testSuite`](#testsuite)
 
@@ -193,7 +193,7 @@ This event represents a Test suite that has has finished, the event will contain
 
 The event represents an artifact that has been packaged for distribution; this artifact is now versioned with a fixed version.
 
-- Event Type: __`dev.cdevents.artifact.packaged`__
+- Event Type: __`dev.cdevents.artifact.packaged.0.1.0-draft`__
 - Predicate: packaged
 - Subject: [`artifact`](#artifact)
 
@@ -206,7 +206,7 @@ The event represents an artifact that has been packaged for distribution; this a
 
 The event represents an artifact that has been published and it can be advertised for others to use.
 
-- Event Type: __`dev.cdevents.artifact.published`__
+- Event Type: __`dev.cdevents.artifact.published.0.1.0-draft`__
 - Predicate: published
 - Subject: [`artifact`](#artifact)
 

core.md

@@ -66,7 +66,7 @@ Due the dynamic nature of Pipelines, most of actual work needs to be queued to
 happen in a distributed way, hence queued events are added. Adopters can choose
 to ignore these events if they don't apply to their use cases.
 
-- Event Type: __`dev.cdevents.pipelinerun.queued`__
+- Event Type: __`dev.cdevents.pipelinerun.queued.0.1.0-draft`__
 - Predicate: queued
 - Subject: [`pipelineRun`](#pipelinerun)
 
@@ -81,7 +81,7 @@ to ignore these events if they don't apply to their use cases.
 
 A pipelineRun has started and it is running.
 
-- Event Type: __`dev.cdevents.pipelinerun.started`__
+- Event Type: __`dev.cdevents.pipelinerun.started.0.1.0-draft`__
 - Predicate: started
 - Subject: [`pipelineRun`](#pipelinerun)
 
@@ -96,7 +96,7 @@ A pipelineRun has started and it is running.
 
 A pipelineRun has finished, successfully or not.
 
-- Event Type: __`dev.cdevents.pipelinerun.finished`__
+- Event Type: __`dev.cdevents.pipelinerun.finished.0.1.0-draft`__
 - Predicate: finished
 - Subject: [`pipelineRun`](#pipelinerun)
 
@@ -113,7 +113,7 @@ A pipelineRun has finished, successfully or not.
 
 A taskRun has started and it is running.
 
-- Event Type: __`dev.cdevents.taskrun.started`__
+- Event Type: __`dev.cdevents.taskrun.started.0.1.0-draft`__
 - Predicate: started
 - Subject: [`taskRun`](#taskrun)
 
@@ -129,7 +129,7 @@ A taskRun has started and it is running.
 
 A taskRun has finished, successfully or not.
 
-- Event Type: __`dev.cdevents.taskrun.finished`__
+- Event Type: __`dev.cdevents.taskrun.finished.0.1.0-draft`__
 - Predicate: finished
 - Subject: [`taskRun`](#taskrun)
 

primer.md

@@ -98,6 +98,75 @@ attributes exists, CDEvents aims to make an official CloudEvents extension for
 the CloudEvents specification and listed with other [documented
 extensions](https://github.com/cloudevents/spec/blob/v1.0.1/documented-extensions.md).
 
+## Versioning
+
+The CDEvents specification and events are versioned independently, both
+following the principle of semantic versioning.
+
+### Versioning of CDEvents
+
+Individual CDEvents are versioned using semantic versioning, with a
+`major.minor.patch` format of the version.
+
+Backward compatible changes are changes that allow existing consumers to parse
+messages with a newer version, have access to the same data as before, as long
+the extra fields are ignored. Broadening the accepted values for a property is a
+backward incompatible change, as the consumer may not be prepared to manage the
+new format of value.
+
+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 versions (e.g. 0.3.1 -> 1.0.0): backward incompatible changes to events.
+  Renamed, moved or removed fields requires a new major version.
+
+- Minor versions (e.g. 0.1.2 -> 0.2.0): backward compatible changes to events
+  that involve a structural change in the schema. A new field is added, a copy
+  of an existing field is added and the old location deprecated, or a new
+
+- Patch versions (e.g. 0.1.0 -> 0.1.1): backward compatible changes to events
+  that do not involve any structural change in the schema, for instance
+  narrowing the accepted values for a property
+
+While the specification of an event is work in progress, its version is tagged
+with an extra `-draft` at the end.
+
+The version of an event is included in its type. This allows for easy filtering
+of events of a specific version, by looking at a single field in the context.
+Examples of full event versions are:
+
+- `dev.cdevents.build.queued.0.1.0-draft`
+- `dev.cdevents.environment.deleted.0.1.0`
+
+### Versioning of the CDEvents specification
+
+The overall CDEvents specification is versioned using semantic versioning, with
+a `major.minor.patch` format of the version. The specification version is
+associated to a git version (tag) in the `cdevents/spec` repository, in the
+format `vMajor.Minor.Patch`.
+
+- A specification that includes only cosmetic fixes is identified by a change in
+  the patch version, for instance 0.1.0 -> 0.1.1
+
+- A specification that includes only backwards compatible change is identified
+  by a change in the minor version, for instance 0.1.3 -> 0.2.0
+
+- A specification that includes at least one backward incompatible change, is
+  identified by a change in the major version, for instance 0.1.2 -> 2.0.0
+
+While a version of the specification is work in progress, its version is tagged
+with an extra `-draft` at the end, for instance 0.1.0-draft.
+
+### Development of a new version
+
+The specification on the main branch is versioned with the number of the next
+version followed by a `-draft`. If any event is modified, its version is changed
+accordingly, followed by a `-draft` as well.
+
+Once a specification is ready for release, its number if updated, the event versions
+are finalized (`-draft` is removed), schemas are updated and a git tag is created for
+this last commit.
+
 ## Acknowledgments
 
 The initial structure of the CDEvents specification format was based on the specification of the [CloudEvents](https://github.com/cloudevents/spec) project.

schemas/artifactpackaged.json

@@ -1,15 +1,15 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cdevents.dev/draft/schema/artifact-packaged-event",
+  "$schema": "https://json-schema.org/0.1.0-draft/2020-12/schema",
+  "$id": "https://cdevents.dev/0.1.0-draft/schema/artifact-packaged-event",
   "properties": {
     "context": {
       "properties": {
         "version": {
           "type": "string",
           "enum": [
-            "draft"
+            "0.1.0-draft"
           ],
-          "default": "draft"
+          "default": "0.1.0-draft"
         },
         "id": {
           "type": "string",

schemas/artifactpublished.json

@@ -1,15 +1,15 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cdevents.dev/draft/schema/artifact-published-event",
+  "$schema": "https://json-schema.org/0.1.0-draft/2020-12/schema",
+  "$id": "https://cdevents.dev/0.1.0-draft/schema/artifact-published-event",
   "properties": {
     "context": {
       "properties": {
         "version": {
           "type": "string",
           "enum": [
-            "draft"
+            "0.1.0-draft"
           ],
-          "default": "draft"
+          "default": "0.1.0-draft"
         },
         "id": {
           "type": "string",

schemas/branchcreated.json

@@ -1,15 +1,15 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cdevents.dev/draft/schema/branch-created-event",
+  "$schema": "https://json-schema.org/0.1.0-draft/2020-12/schema",
+  "$id": "https://cdevents.dev/0.1.0-draft/schema/branch-created-event",
   "properties": {
     "context": {
       "properties": {
         "version": {
           "type": "string",
           "enum": [
-            "draft"
+            "0.1.0-draft"
           ],
-          "default": "draft"
+          "default": "0.1.0-draft"
         },
         "id": {
           "type": "string",

schemas/branchdeleted.json

@@ -1,15 +1,15 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://cdevents.dev/draft/schema/branch-deleted-event",
+  "$schema": "https://json-schema.org/0.1.0-draft/2020-12/schema",
+  "$id": "https://cdevents.dev/0.1.0-draft/schema/branch-deleted-event",
   "properties": {
     "context": {
       "properties": {
         "version": {
           "type": "string",
           "enum": [
-            "draft"
+            "0.1.0-draft"
           ],
-          "default": "draft"
+          "default": "0.1.0-draft"
         },
         "id": {
           "type": "string",