Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add glossary #237

Merged
merged 5 commits into from
May 18, 2020
Merged

Add glossary #237

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
15cd684
Add glossary
e-backmark-ericsson May 6, 2020
a14eb03
Multiple updates
e-backmark-ericsson May 7, 2020
506f310
Elaborate on Composition and CL
e-backmark-ericsson May 7, 2020
cdbd6b4
Add link definition and elaborate more on eg. event definition
e-backmark-ericsson May 8, 2020
5ac6b05
Fix grammatical error
e-backmark-ericsson May 11, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
102 changes: 102 additions & 0 deletions eiffel-syntax-and-usage/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
<!---
Copyright 2020 Ericsson AB.
For a full list of individual contributors, please see the commit history.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
--->

# Eiffel Glossary
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)
e-backmark-ericsson marked this conversation as resolved.
Show resolved Hide resolved
- [Activity](#activity)
- [Artifact](#artifact)
- [Composition](#composition)
- [Confidence Level](#confidence-level)
- [Environment](#environment)
- [Event](#event)
- [Source Change](#source-change)
- [Submit](#submit)

- [Terms Used in Documentation](#terms-used-in-documentation)
- [Pipeline](#pipeline)

## 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. 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), 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.

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).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This definition is enough, but maybe we could add that artifacts aren't always only things that will be included in products?
They can also be test artifacts, i.e. artifacts only created to be useful in some specific test scenario. For example, when product software is combined with testing harnesses. Such artifacts are also defined by Baselines to record what versions of testing harness software were used.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. Will add something along those lines.


#### Examples of events related to artifacts:
- [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md)

### Composition
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good definition!

As with Artifacts, we could add a comment/example of how Compositions/Baselines can be used to record test environments as well as product hierarchies.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, will do.

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), 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".

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).
Copy link

@eradam eradam May 8, 2020 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, good definition, I have heard many times that people still don't understand really what an event is/should be.
It is not a message sent intending to cause some side effect somewhere like a remote procedure call. It is just a notification to the world that something has happened. As such, an event should not contain information that is not directly associated with what happened, even if it is tempting to use them as carriers of general "system" type information.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. I'll elaborate a bit more on the event definition, and probably also add a link definition explaining a chain of events.


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