From cdbd6b4e6603b07c5df94661ba94519aecf85586 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emil=20B=C3=A4ckmark?= Date: Fri, 8 May 2020 15:08:12 +0200 Subject: [PATCH] Add link definition and elaborate more on eg. event definition --- eiffel-syntax-and-usage/glossary.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/eiffel-syntax-and-usage/glossary.md b/eiffel-syntax-and-usage/glossary.md index 99e9c2a0..653b9988 100644 --- a/eiffel-syntax-and-usage/glossary.md +++ b/eiffel-syntax-and-usage/glossary.md @@ -25,6 +25,7 @@ This a non-exhaustive, alphabetical list of terms used in the [Eiffel vocabulary - [Confidence Level](#confidence-level) - [Environment](#environment) - [Event](#event) + - [Link](#link) - [Source Change](#source-change) - [Submit](#submit) @@ -52,13 +53,15 @@ Some activity types have their own specific events, such as EiffelTestCase\*Even - [EiffelTestCaseFinishedEvent](../eiffel-vocabulary/EiffelTestCaseFinishedEvent.md) ### Artifact -_Artifacts_ are items or software packages generated in a CI/CD [pipeline](#pipeline), for example a built binary or a Docker image. An artifact should be possible to identify using a purl (package URL). An artifact is often the subject of a test executed or a delivery performed within a CI/CD [pipeline](#pipeline). +_Artifacts_ are items or software packages generated in a CI/CD [pipeline](#pipeline), for example a built binary or a Docker image. An artifact should be possible to identify using a purl (package URL). Artifacts often refer to a [composition](#composition) stating exactly what versions of different software pieces where put together to form the artifact. + +An artifact is often the subject of a test executed or a delivery performed within a CI/CD pipeline. An artifact can also be software package generated with the sole purpose to be used in a specific test scenario. For example when product software is combined with test harnesses. Such artifacts are also defined by compositions to record what versions of test harness software were used. #### Examples of events related to artifacts: - [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) ### Composition -A _composition_ is an immutable grouping of specific versions of [artifacts](#artifact) and/or [source changes](#source-change). It is more or less the same as what is elsewhere sometimes referred to as a _baseline_, which can be explained as being a fixed reference point used for comparison. A composition is often defined with the purpose of enabling downstream [artifacts](#artifact) to be generated. +A _composition_ is an immutable grouping of specific versions of [artifacts](#artifact) and/or [source changes](#source-change). It is more or less the same as what is elsewhere sometimes referred to as a _baseline_, which can be explained as being a fixed reference point used for comparison. A composition is often defined with the purpose of enabling downstream artifacts to be generated. It gives full traceability on what software pieces that were used to generate the artifact, being it a product artifact, a test harness or some other kind of generated artifact. #### Examples of events related to compositions: - [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) @@ -80,7 +83,16 @@ An Eiffel _environment_ defines the environment in which an [activity](#activity - [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md) ### Event -An Eiffel _event_ is a broadcast notification telling any consumer about an event occurring in the CI/CD [pipeline](#pipeline). +An Eiffel _event_ is a broadcast notification telling any consumer about an event occurring in the CI/CD [pipeline](#pipeline). As opposed to a _message_, that is addressed to a certain receiver, an event is not aimed at a specific consumer. An event is also _descriptive_ rather than _prescriptive_, meaning that it does not expect a certain action to happen but it instead notifies on actions performed. + +An event should not carry any data that is already provided by events sent earlier in the CI/CD pipeline. Instead those earlier events should be [linked](#link) from this event, making it possible to aggregate all relevant data connected to the CI/CD pipeline execution. + +More about what an event is supposed to be can be read in the [event design guidelines](./event-design-guidelines.md). + +### Link +A _link_ is a directed connection between two [events](#event). With linked events you will get a directed acyclic graph of actions performed in your CI/CD [pipeline](#pipeline). Links are also semantic, as each link has a type describing the relationship between the link source and its target. Having linked events enables generic data aggregations and visualizations to be implemented. Together with the timestamps provided in each event, the directed semantic links enable the possibility to create generic pipeline measurements and other analytics compilations. + +More about links can be read in the [links object documentation](./the-links-object.md). ### Source Change A _source change_ is the unit of a review. It results in a single commit when merged to the Git repository. @@ -99,4 +111,4 @@ A _submit_ is the action of merging a [source change](#source-change) to its int The terms below are not used in any events in the Eiffel protocol. They are added here to enable a homogenous and easy read of the protocol documentation. These terms are subject to change without notice if a better name is found or defined elsewhere. Their names should reflect the most commonly used terms elsewhere in the industry. ### Pipeline -A _pipeline_ is an ordered set of [activities](#activity) often triggered by a source change being created or submitted. +A _pipeline_ is an ordered set of [activities](#activity) often triggered by a [source change](#source-change) being created or [submitted](#submit).