diff --git a/spec.md b/spec.md index e5563665..47bc50b3 100644 --- a/spec.md +++ b/spec.md @@ -6,31 +6,161 @@ description: > Introduction to CDEvents and specification of common metadata --- --> -# Continuous Delivery Events Vocabulary +# CDEvents - Draft -__Note:__ This is a work-in-progress draft version and is being worked on by members of the Events SIG. You are very welcome to join the work and the discussions! +__Note:__ This is a work-in-progress version and is being worked on by members +of the CDEvents project. You are very welcome to +[join the work and the discussions](https://github.com/cdevents)! -This document intends to describe a set of events related to different phases of a Continuous Delivery process. -These events are categorized by meaning, and the phase where they are intended to be used. -These events are agnostic from any specific tool and are designed to fit a wide range of scenarios. +## Abstract -The phases covered by this proposal are: +CDEvents is a common specification for Continuous Delivery events. -- __[Core Events](core.md)__: includes core events related to core activities and orchestration that needs to exist to be able to deterministically and continuously being able to delivery software to users. -- __[Source Code Version Control Events](source-code-version-control.md)__: Events emitted by changes in source code or by the creation, modification or deletion of new repositories that hold source code. -- __[Continuous Integration Pipelines Events](continuous-integration-pipeline-events.md)__: includes events related to building, testings, packaging and releasing software artifacts, usually binaries. -- __[Continuous Deployment Pipelines Events](continuous-deployment-pipeline-events.md)__: include events related with environments where the artifacts produced by the integration pipelines actually run. These are usually services running in a specific environment (dev, QA, production), or embedded software running in a specific hardware. +## Overview -These phases can also be considered as different profiles of the vocabulary that can be adopted independently. -Also notice that we currently use the term 'pipeline' to denote a pipelines, workflows and related concepts. We also use the term 'task' to denote a job/stage/step. +The specification is structured in two main parts: -## Required Metadata for CD Events +- The [*context*](context), made of mandatory and optional *fields*, shared by + all events +- The [*vocabulary*](vocabulary), which identifies *activities*, their + associated *events* and *schema* -The following attributes are REQUIRED to be present in all the Events defined in this vocabulary: +## Notations and Terminology + +### Notational Conventions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). + +For clarity, when a feature is marked as "OPTIONAL" this means that it is +OPTIONAL for both the [Producer](#producer) and [Consumer](#consumer) of a +message to support that feature. In other words, a producer can choose to +include that feature in a message if it wants, and a consumer can choose to +support that feature if it wants. A consumer that does not support that feature +will then silently ignore that part of the message. The producer needs to be +prepared for the situation where a consumer ignores that feature. An +[Intermediary](#intermediary) SHOULD forward OPTIONAL attributes. + +### Terminology + +__Note__: CDEvents adopts, wherever applicable, the terminology used by +[CloudEvents](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#notational-conventions). Some of the definitions below are borrowed +from that specification. + +This specification defines the following terms: + +#### Occurrence + +An "occurrence" is the capture of a statement of fact during the operation of a +software system. This might occur because of a signal raised by the system or a +signal being observed by the system, because of a state change, because of a +timer elapsing, or any other noteworthy activity. For example, a device might go +into an alert state because the battery is low, or a virtual machine is about to +perform a scheduled reboot. + +#### Event + +An "event" is a data record expressing an occurrence and its context. Events are +routed from an event producer (the source) to interested event consumers. The +routing can be performed based on information contained in the event, but an +event will not identify a specific routing destination. + +#### Producer + +The "producer" is a specific instance, process or device that creates the data +structure describing the CDEvent. + +#### Source + +The "source" is the context in which the occurrence happened. In a distributed +system it might consist of multiple [Producers](#producer). If a source is not +aware of CDEvents, an external producer creates the CDEvent on behalf of +the source. + +#### Consumer + +A "consumer" receives the event and acts upon it. It uses the context and data +to execute some logic, which might lead to the occurrence of new events. + +#### Intermediary + +An "intermediary" receives a message containing an event for the purpose of +forwarding it to the next receiver, which might be another intermediary or a +[Consumer](#consumer). A typical task for an intermediary is to route the event +to receivers based on the information in the [Context](#context). + +### Subject + +The "subject" is the entity with which the occurrence in a software system +is concerned. For instance when a software build is started, the build is the +subject of the occurrence, or when a service is deployed, the subject is the service. Subjects have a schema associated, defined in the +[vocabulary](#vocabulary). Subjects belong to two main categories: + +- long running, which stay in a running state until they're purposely stopped or + encounter a failure or a condition that prevents them from running - for + example a service or an environment +- run to completion, which independently stop after they accomplished (or + failed to) a specific task, or encounter a failure or a condition that + prevents them from continuing - for example a task run, a build or a test + +### Action + +An "action" is what happens to a subject in an occurrence. +For instance in case of a software build, started is a valid action in the +occurrence, or in case of a service, deployed in a valid action. Valid actions +are defined in the [vocabulary](#vocabulary). + +## Context + +The following attributes are REQUIRED to be present in all the Events defined in +this vocabulary: - __Event ID__: defines a unique identifier for the event -- __Event Type__: defines a textual description of the event type, only event types described in this document are supported. All event types should be prefixed with `dev.cdevents.` +- __Event Type__: defines the type of event, as combination of a *subject* and + *action*. Valid event types are defined in the [vocabulary](#vocabulary). All + event types should be prefixed with `dev.cdevents.`. One occurrence may have + multiple events associated, as long as they have a different event type + associated - __Event Source__: defines the context in which an event happened - __Event Timestamp__: defines the time when the event was produced -The following sections list the events in different phases, allowing adopters to choose the events that they are more interested in. +## Vocabulary + +The vocabulary defines *subjects*, their associated *actions* and *fields*. +An example of *subject* is a `build`. The `build` can be `started` or +`finished`, which are the actions. The `build` entity has a schema which defines +mandatory and optional *fields*. *Subjects* can represent the core context of an +event, but may also be referenced to in other areas of the protocol. + +The *subjects* are grouped, to help browsing the spec, in different buckets, +which are associated to different parts of a Continuous Delivery Process where +they are expected to be *produced*. + +These *subjects*, with their associated *actions* and *fields*, are agnostic +from any specific tool and are designed to fit a wide range of scenarios. The +CDEvents project collaborates with the +[SIG Interoperability](https://github.com/cdfoundation/sig-interoperability) to +identify a the common terminology to be used and how it maps to different terms +in different platforms. + +The groups (or buckets) defined are: + +- __[Core](core.md)__: includes core events related to core activities and + orchestration that needs to exist to be able to deterministically and + continuously being able to delivery software to users. +- __[Source Code Version Control](source-code-version-control.md)__: Events + emitted by changes in source code or by the creation, modification or deletion + of new repositories that hold source code. +- __[Continuous Integration](continuous-integration-pipeline-events.md)__: + includes events related to building, testings, packaging and releasing + software artifacts, usually binaries. +- __[Continuous Deployment](continuous-deployment-pipeline-events.md)__: include + events related with environments where the artifacts produced by the + integration pipelines actually run. These are usually services running in a + specific environment (dev, QA, production), or embedded software running in a + specific hardware. + +The grouping may serve in future as a reference for different CDEvents +compliance profiles, which can be supported individually by implementing +platforms.