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 predicates.

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,136 @@ 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 *attributes*, shared
+  by all events
+- The [*vocabulary*](vocabulary), which identifies *event types*, structures as
+  *subjects* and *predicates*
 
-The following attributes are REQUIRED to be present in all the Events defined in this vocabulary:
+## Notations and Terminology
 
-- __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.`
+### 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).
+Specifically, the following terms are borrowed from the CloudEvents spec:
+
+- [*Occurrence*](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#occurrence)
+- [*Producer*](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#producer)
+- [*Source*](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#source)
+- [*Consumer*](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#consumer)
+- [*Intermediary*](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#intermediary)
+
+The CDEvents specification additionally defines the following terms:
+
+#### 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.
+
+#### 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 list of *attributes* 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, an environment, an artifact or a source change
+- 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
+
+#### Predicate
+
+A "predicate" is what happened to a subject in an occurrence.
+For instance in case of a software build, started is a valid predicate in the
+occurrence, or in case of a service, deployed in a valid predicate. Valid
+predicate 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 an identifier for the event. The Event ID MUST be unique
+  within the given Event Source.
+- __Event Type__: defines the type of event, as combination of a *subject* and
+  *predicate*. 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 different event types
 - __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 *event types*, which are made of *subjects*, and
+*predicates*. An example of *subject* is a `build`. The `build` can be `started`
+or `finished`, which are the predicates. The `build` subject has several
+*attributes* associated; the *event type* schema defines which ones are
+mandatory and which ones are optional. *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 *stages*,
+which are associated to different parts of a Continuous Delivery process where
+they are expected to be *produced*.
+
+These *subjects*, with their associated *predicates* and *attributes*, 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 *stages* 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.