Reformat the spec root page, add subject and actions

Restructure a the spec root page, add more sections and introduce
the initial terminology, including subjects and actions.

This provides the basis for restructuring the vocabulary and
defining the schemas that will be used to build the SDKs.

Partially addresses: #12
Related to: #11

Signed-off-by: Andrea Frittoli <andrea.frittoli@gmail.com>

spec.md

@@ -6,31 +6,162 @@ 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).
+
+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 CDEvent, 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
+
+A "subject" is the part of a software system that is involved in an occurrence.
+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 events. 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, for easiness of consultation, 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.