From 15cd684962668fb6ea7632d12f2e3390a819b087 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emil=20B=C3=A4ckmark?= Date: Wed, 6 May 2020 17:18:01 +0200 Subject: [PATCH 1/5] Add glossary --- README.md | 1 + eiffel-syntax-and-usage/glossary.md | 65 +++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+) create mode 100644 eiffel-syntax-and-usage/glossary.md diff --git a/README.md b/README.md index a356251d..91cc9782 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ Visit [Eiffel Community](https://eiffel-community.github.io) to get started and 1. [How to Propose Changes and Contribute](./CONTRIBUTING.md) 1. [Code of Conduct](./CODE_OF_CONDUCT.md) 1. Eiffel Syntax and Usage + 1. [Eiffel Glossary](./eiffel-syntax-and-usage/glossary.md) 1. [Event Design Guidelines](./eiffel-syntax-and-usage/event-design-guidelines.md) 1. [Event Structure](./eiffel-syntax-and-usage/event-structure.md) 1. [The Meta Object](./eiffel-syntax-and-usage/the-meta-object.md) diff --git a/eiffel-syntax-and-usage/glossary.md b/eiffel-syntax-and-usage/glossary.md new file mode 100644 index 00000000..ed28baa4 --- /dev/null +++ b/eiffel-syntax-and-usage/glossary.md @@ -0,0 +1,65 @@ + + +# Eiffel Glossary +This a non-exhaustive, alphabetical list of terms used in the Eiffel Vocabulary and its documentation. + + - [Terms Used in Event Definitions](#terms-used-in-event-definitions) + - [Activity](#activity) + - [Artifact](#artifact) + - [Environment](#environment) + - [Event](#event) + - [Source Change](#source-change) + - [Submit](#submit) + + - [Terms Used in Documentation](#terms-used-in-documentation) + - [Pipeline](#pipeline) + - [Step](#step) + +## Terms Used in Event Definitions +These terms are either part of the event names in the Eiffel Vocabulary, or they are part of parameter names or values in the events. Users of Eiffel should be able to rely on these terms to be kept, unless a major change to event types are done. + +### Activity +An _activity_ is any kind of action in a CI/CD system, normally triggered by an operation done in an SCM system or by a previous activity. It's purpose is to notify what is going on and what has finished, and when, and with what outcome. + +Activities are hierarchical. Activities could be whole [pipelines](#pipeline), [pipeline steps](#pipeline-step) or any level of pipeline sub steps. And those steps could for example be build activities or test activities. + +An activity could also be an SCM operation such as a manual code review or automated source change check. + +### 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). + +### Environment +An Eiffel _environment_ defines the environment in which an [activity](#activity) is executed. Could be for example a host, node, service name/uri, a Docker image or some other kind of machine configuration definition. + +### Event +An Eiffel _event_ is a broadcast notification telling any consumer about an event occurring in the CI/CD [pipeline](#pipeline). + +### Source Change +A _source change_ is the unit of a review. It results in a single commit when merged to the Git repository. + +### Submit +A _submit_ is the action of merging a [source change](#source-change) to its intended target branch. + +## Terms Used in Documentation +These terms are not defined by Eiffel. They are added here to enable a homogenous and easy read protocol documentation. These terms are subject to change without notice if a better name is found or defined elsewhere. + +### Pipeline +A _pipeline_ is an ordered set of [pipeline steps](#pipeline-step) often triggered by a source change being created or submitted. + +### Pipeline Step +A _pipeline step_ is used in the Eiffel protocol documentation to exemplify operations executed in a [pipeline](#pipeline). From a14eb037fbf2a58962d0110e2172d80a9320b6d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emil=20B=C3=A4ckmark?= Date: Thu, 7 May 2020 12:52:50 +0200 Subject: [PATCH 2/5] Multiple updates --- eiffel-syntax-and-usage/glossary.md | 57 ++++++++++++++++++++++++----- 1 file changed, 47 insertions(+), 10 deletions(-) diff --git a/eiffel-syntax-and-usage/glossary.md b/eiffel-syntax-and-usage/glossary.md index ed28baa4..e2f32caa 100644 --- a/eiffel-syntax-and-usage/glossary.md +++ b/eiffel-syntax-and-usage/glossary.md @@ -16,11 +16,13 @@ ---> # Eiffel Glossary -This a non-exhaustive, alphabetical list of terms used in the Eiffel Vocabulary and its documentation. +This a non-exhaustive, alphabetical list of terms used in the [Eiffel vocabulary](../eiffel-vocabulary/) and its documentation. - [Terms Used in Event Definitions](#terms-used-in-event-definitions) - [Activity](#activity) - [Artifact](#artifact) + - [Composition](#composition) + - [Confidence Level](#confidence-level) - [Environment](#environment) - [Event](#event) - [Source Change](#source-change) @@ -28,38 +30,73 @@ This a non-exhaustive, alphabetical list of terms used in the Eiffel Vocabulary - [Terms Used in Documentation](#terms-used-in-documentation) - [Pipeline](#pipeline) - - [Step](#step) ## Terms Used in Event Definitions These terms are either part of the event names in the Eiffel Vocabulary, or they are part of parameter names or values in the events. Users of Eiffel should be able to rely on these terms to be kept, unless a major change to event types are done. ### Activity -An _activity_ is any kind of action in a CI/CD system, normally triggered by an operation done in an SCM system or by a previous activity. It's purpose is to notify what is going on and what has finished, and when, and with what outcome. +An _activity_ is any kind of action in a CI/CD system, normally triggered by an operation done in an SCM system or by a previous activity. The Eiffel protocol declares events related to activities to describe what is going on, what has finished, when did it happen and with what outcome. -Activities are hierarchical. Activities could be whole [pipelines](#pipeline), [pipeline steps](#pipeline-step) or any level of pipeline sub steps. And those steps could for example be build activities or test activities. +Activities are hierarchical. Activities could be whole [pipelines](#pipeline), or sequential or parallel parts thereof. Such pipeline parts could for example be build activities or test activities. -An activity could also be an SCM operation such as a manual code review or automated source change check. +An activity could also be an SCM operation such as a manual code review or automated source change check. + +Some activity types have their own specific events, such as EiffelTestCase\*Events notifying test case executions, while others are more generic and can be notified using EiffelActivity\*Events. + +#### Examples of events related to activities: +- [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md) +- [EiffelActivityStartedEvent](../eiffel-vocabulary/EiffelActivityStartedEvent.md) +- [EiffelActivityFinishedEvent](../eiffel-vocabulary/EiffelActivityFinishedEvent.md) +- [EiffelTestCaseTriggeredEvent](../eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md) +- [EiffelTestCaseStartedEvent](../eiffel-vocabulary/EiffelTestCaseStartedEvent.md) +- [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). +#### Examples of events related to artifacts: +- [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) + +### Composition +A _composition_ is a grouping of [artifacts](#artifact) and/or [source changes](#source-change). A composition is more or less the same as what is elsewhere sometimes referred to as a _baseline_. + +#### Examples of events related to compositions: +- [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) + +### Confidence Level +A _confidence level_ can be achieved for an [artifact](#artifact) or a [composition](#composition). It can be used to annotate that the artifact or composition has been tested up to a certain level, that it has reached a certain level of maturity, or that it has passed a certain criteria. Examples of confidence levels could be "smokeTestsOk", "releasable" or "released". + +A confidence level can group other (sub) confidence levels of lower abstractions. For example the confidence level "allTestsOk" could summarize sub confidence levels called "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk". + +Confidence levels frequently figure in automated delivery interfaces within a tiered system context: lower level tiers issue an agreed confidence level signaling that a new version is ready for integration in a higher level tier. + +#### Examples of events related to confidence levels: +- [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md) + ### Environment An Eiffel _environment_ defines the environment in which an [activity](#activity) is executed. Could be for example a host, node, service name/uri, a Docker image or some other kind of machine configuration definition. +#### Examples of events related to environments: +- [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). ### Source Change A _source change_ is the unit of a review. It results in a single commit when merged to the Git repository. +#### Examples of events related to source changes: +- [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md) +- [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md) + ### Submit A _submit_ is the action of merging a [source change](#source-change) to its intended target branch. +#### Examples of events related to submits: +- [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md) + ## Terms Used in Documentation -These terms are not defined by Eiffel. They are added here to enable a homogenous and easy read protocol documentation. These terms are subject to change without notice if a better name is found or defined elsewhere. +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 [pipeline steps](#pipeline-step) often triggered by a source change being created or submitted. - -### Pipeline Step -A _pipeline step_ is used in the Eiffel protocol documentation to exemplify operations executed in a [pipeline](#pipeline). +A _pipeline_ is an ordered set of [activities](#activity) often triggered by a source change being created or submitted. From 506f3103984045fcc9c1b72c2ee094de21feb14d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emil=20B=C3=A4ckmark?= Date: Thu, 7 May 2020 18:06:19 +0200 Subject: [PATCH 3/5] Elaborate on Composition and CL --- eiffel-syntax-and-usage/glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/eiffel-syntax-and-usage/glossary.md b/eiffel-syntax-and-usage/glossary.md index e2f32caa..99e9c2a0 100644 --- a/eiffel-syntax-and-usage/glossary.md +++ b/eiffel-syntax-and-usage/glossary.md @@ -58,13 +58,13 @@ _Artifacts_ are items or software packages generated in a CI/CD [pipeline](#pipe - [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) ### Composition -A _composition_ is a grouping of [artifacts](#artifact) and/or [source changes](#source-change). A composition is more or less the same as what is elsewhere sometimes referred to as a _baseline_. +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. #### Examples of events related to compositions: - [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) ### Confidence Level -A _confidence level_ can be achieved for an [artifact](#artifact) or a [composition](#composition). It can be used to annotate that the artifact or composition has been tested up to a certain level, that it has reached a certain level of maturity, or that it has passed a certain criteria. Examples of confidence levels could be "smokeTestsOk", "releasable" or "released". +A _confidence level_ can be achieved for an [artifact](#artifact), a [composition](#composition), or a [source change](#source-change). It can be used to annotate that the artifact, composition or source change has been tested up to a certain level, that it has reached a certain level of maturity, or that it has passed a certain criteria. Examples of confidence levels could be "smokeTestsOk", "releasable" or "released". A confidence level can group other (sub) confidence levels of lower abstractions. For example the confidence level "allTestsOk" could summarize sub confidence levels called "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk". 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 4/5] 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). From 5ac6b05896301463ddae51f829e2f2ccc2376265 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emil=20B=C3=A4ckmark?= Date: Mon, 11 May 2020 13:28:55 +0200 Subject: [PATCH 5/5] Fix grammatical error --- eiffel-syntax-and-usage/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eiffel-syntax-and-usage/glossary.md b/eiffel-syntax-and-usage/glossary.md index 653b9988..f88c3d67 100644 --- a/eiffel-syntax-and-usage/glossary.md +++ b/eiffel-syntax-and-usage/glossary.md @@ -61,7 +61,7 @@ An artifact is often the subject of a test executed or a delivery performed with - [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 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. +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, be 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)