Add support for experimental event versions (#343)

magnusbaeck · e-backmark-ericsson · web-flow · commit 37b2d1b7213a · 2023-02-09T12:38:17.000+01:00
Document how experimental event versions work and add words of
caution in a couple of places in the documentation template.

Co-authored-by: Emil Bäckmark &lt;emil.backmark@ericsson.com&gt;
diff --git a/eiffel-syntax-and-usage/event-schemas.md b/eiffel-syntax-and-usage/event-schemas.md
@@ -31,6 +31,7 @@ Both schemas and documentation files are generated from _schema definition files
 | `_links.<link type>.description`  | A description of the link type. |
 | `_links.<link type>.required`     | A boolean value indicating whether a link of this type is required. Optional, default false. |
 | `_links.<link type>.multiple`     | A boolean value indicating whether multiple links of this type is allowed. Optional, default false. |
+| `_links.<link type>.experimental` | A boolean value indicating whether the link type is experimental, i.e. the only valid target is an experimental event type. Optional, default false. |
 | `_links.<link type>.targets.any_type`  | A boolean value indicating whether the link can point to an event of any type. |
 | `_links.<link type>.targets.types`     | A string array of event names that the link type may point to. Must be non-empty if `any_type` is false, and must be empty if `any_type` is true. |
 | `_history`      | An array of objects describing the event type's version history, up to and including the current version. The items should be sorted in reverse order. |
diff --git a/eiffel-syntax-and-usage/versioning.md b/eiffel-syntax-and-usage/versioning.md
@@ -58,3 +58,8 @@ As with any software, historical versions may need to be updated occasionally. U
 * If 2.0.0 and 2.0.1 exist, the 2.0.0 event may not serve as a baseline for new versions. Instead the 2.0.1 event shall be used as baseline for changes to the event type.
 
 Users are not bound to use only event types included in an edition. To exemplify, a consumer may accept all [edition-toulouse](../../../tree/edition-toulouse) events, plus [EiffelIssueVerifiedEvent](../eiffel-vocabulary/EiffelIssueVerifiedEvent.md) 2.0.0, which is not included in that edition. Indeed, it may also accept additional events not included at all, such as [EiffelIssueDefinedEvent](../eiffel-vocabulary/EiffelIssueDefinedEvent.md). In this sense, editions are non-exclusive. That being said, if there is a need to identify a collection of events updated from a historical edition, a new edition may be created for that purpose. The naming scheme of such editions SHALL be `<baseline edition name>-<increment integer starting at 1>`. To exemplify, an updated [edition-toulouse](../../../tree/edition-toulouse) would be named `edition-toulouse-1`, while a subsequent one would be named `edition-toulouse-2`, et cetera.
+
+## Experimental event versions
+To allow for experimentation with new event types that require actual usage to be fully understood and evaluated, pre-1.0.0 version numbers may be used. The first experimental version of an event is 0.1.0, and stepping the minor and patch components of such versions is done in the usual manner except the important difference that backwards incompatible changes may take place in any 0.x.y version. The introduction of a 0.x.y version of an event type does not imply that there will ever be a 1.0.0 version; it may be abandoned and not included in subsequent protocol editions.
+
+Other events types may link to events that only exist as experimental. Normal rules apply when adding or removing such link types from a source event, i.e. adding the link requires a minor version stepping and removing it again (e.g. if the experimental event type is abandoned) requires a major version stepping. The source event type documentation should note that the target event type is experimental and that the link type may be removed in a later version.
diff --git a/eiffel-vocabulary/EiffelActivityCanceledEvent.md b/eiffel-vocabulary/EiffelActivityCanceledEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelActivityCanceledEvent (ActC)
+
 The EiffelActivityCanceledEvent signals that a previously triggered activity execution has been canceled _before it has started_. This is typically used in queuing situations where a queued execution is dequeued. It is recommended that __CAUSE__ links be used to indicate the reason.
 
 ## Data Members
diff --git a/eiffel-vocabulary/EiffelActivityFinishedEvent.md b/eiffel-vocabulary/EiffelActivityFinishedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelActivityFinishedEvent (ActF)
+
 The EiffelActivityFinishedEvent declares that a previously started activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md) followed by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)) has finished.
 
 ## Data Members
diff --git a/eiffel-vocabulary/EiffelActivityStartedEvent.md b/eiffel-vocabulary/EiffelActivityStartedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelActivityStartedEvent (ActS)
+
 The EiffelActivityStartedEvent declares that a previously triggered activity (declared by [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md)) has started.
 
 ## Data Members
diff --git a/eiffel-vocabulary/EiffelActivityTriggeredEvent.md b/eiffel-vocabulary/EiffelActivityTriggeredEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelActivityTriggeredEvent (ActT)
+
 The EiffelActivityTriggeredEvent declares that a certain activity - typically a build, test or analysis activity - has been triggered by some factor. Note that this is crucially different from the activity execution having _started_ (as declared by [EiffelActivityStartedEvent](./EiffelActivityStartedEvent.md)).
 
 In a situation where execution follows immediately upon triggering these two events should be sent together. Where that is not the case (e.g. due to queuing) the time delta between EiffelActivityTriggeredEvent and EiffelActivityStartedEvent constitutes the queue time.
diff --git a/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md b/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelAnnouncementPublishedEvent (AnnP)
+
 The EiffelAnnouncementPublishedEvent represents an announcement, technically regarding any topic but typically used to communicate any incidents or status updates regarding the continuous integration and delivery pipeline. This information can then be favorably displayed in visualization and dashboarding applications.
 
 ## Data Members
diff --git a/eiffel-vocabulary/EiffelArtifactCreatedEvent.md b/eiffel-vocabulary/EiffelArtifactCreatedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelArtifactCreatedEvent (ArtC)
+
 The EiffelArtifactCreatedEvent declares that a software artifact has been created, what its coordinates are, what it contains and how it was created.
 
 ## Data Members
diff --git a/eiffel-vocabulary/EiffelArtifactPublishedEvent.md b/eiffel-vocabulary/EiffelArtifactPublishedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelArtifactPublishedEvent (ArtP)
+
 The EiffelArtifactPublishedEvent declares that a software artifact (declared by [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md)) has been published and is consequently available for retrieval at one or more locations.
 
 ## Data Members
diff --git a/eiffel-vocabulary/EiffelArtifactReusedEvent.md b/eiffel-vocabulary/EiffelArtifactReusedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelArtifactReusedEvent (ArtR)
+
 The EiffelArtifactReusedEvent declares that an identified [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md) has been _reused_ for an identified [EiffelCompositionDefinedEvent](./EiffelCompositionDefinedEvent.md). This means that it is logically equivalent to an artifact that would have been built from that composition, and can be used for build avoidance (see the [Build Avoidance Usage Example](../usage-examples/build-avoidance.md) for more information).
 
 The event has no data members, but solely relies on its two required link types __REUSED_ARTIFACT__ and __COMPOSITION__ (see below).
diff --git a/eiffel-vocabulary/EiffelCompositionDefinedEvent.md b/eiffel-vocabulary/EiffelCompositionDefinedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelCompositionDefinedEvent (CD)
+
 The EiffelCompositionDefinedEvent declares a composition of items (artifacts, sources and other compositions) has been defined, typically with the purpose of enabling further downstream artifacts to be generated.
 
 ## Data Members
diff --git a/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md b/eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelConfidenceLevelModifiedEvent (CLM)
+
 The EiffelConfidenceLevelModifiedEvent declares that an entity has achieved (or failed to achieve) a certain level of confidence, or in a broader sense to annotate it as being applicable or relevant to a certain case (e.g. fit for release to a certain customer segment or having passed certain criteria). This is particularly useful for promoting various engineering artifacts, such as product revisions, through the continuous integration and delivery pipeline.
 
 Confidence levels may operate at high or low levels of abstraction - ranging from "smokeTestsOk" to "releasable" or "released" - and they may group other confidence levels of lower abstraction levels. They may also be general or very niched, e.g. "releasable" or "releasableToCustomerX". 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.
diff --git a/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md b/eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelEnvironmentDefinedEvent (ED)
+
 The EiffelEnvironmentDefinedEvent declares an environment which may be referenced from other events in order to secure traceability to the conditions under which an artifact was created or a test was executed. Depending on the technology domain, the nature of an environment varies greatly however: it may be a virtual image, a complete mechatronic system of millions of independent parts, or anything in between. Consequently, a concise yet complete and generic syntax for describing any environment is futile.
 
 From Eiffel's point of view, however, the prioritized concern is not _description_ of the environment, but rather unambiguous _identification_ of it. Consequently, the EiffelEnvironmentDefinedEvent syntax offers several alternatives to be selected from depending on the use case at hand: an environment may be described using __data.image__, __data.host__ or __data.uri__, or a __RUNTIME_ENVIRONMENT__ link to another event that provides a more comprehensive description. Unless a link of the latter kind is used exactly one of these properties SHOULD be included in any one event. In certain situations where an actual description of the environment is deemed redundant or its nature is implicit, the event MAY be used without any of these properties or a RUNTIME_ENVIRONMENT link; it should be noted, however, that _explicit_ practices are always encouraged over _implicit_ ones.
diff --git a/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md b/eiffel-vocabulary/EiffelFlowContextDefinedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelFlowContextDefinedEvent (FCD)
+
 The EiffelFlowContextDefinedEvent describes the context of other events, answering questions such as "Which project is this change part of?" or "Which track does this artifact belong to?". In this way it offers a method of classifying and structuring one's continuous integration and delivery system and thereby facilitating traceability and searchability.
 
 The nature of the described context can vary. The event consequently offers a high degree of flexibility in its description, and none of its member fields are mandatory. Instead they can picked and mixed to fit the situation.
diff --git a/eiffel-vocabulary/EiffelIssueDefinedEvent.md b/eiffel-vocabulary/EiffelIssueDefinedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelIssueDefinedEvent (ID)
+
 The EiffelIssueDefinedEvent declares that an issue has been created in some external issue management software. ID is semantically similar to [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) and [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md).
 
 ## Data Members
diff --git a/eiffel-vocabulary/EiffelIssueVerifiedEvent.md b/eiffel-vocabulary/EiffelIssueVerifiedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelIssueVerifiedEvent (IV)
+
 The EiffelIssueVerifiedEvent declares that an issue, typically a requirement, has been verified by some means. It is different from [EiffelTestCaseFinishedEvent](./EiffelTestCaseFinishedEvent.md) in that multiple test case executions may serve as the basis for a single verification or, conversely, multiple issues may be verified based on a single test case execution.
 
 EiffelIssueVerifiedEvent has no data members, instead relying on its required link types. While "SUCCESSFUL_ISSUE", "FAILED_ISSUE", and "INCONCLUSIVE_ISSUE" are all marked as not required, at least one link of at least one of these types MUST be present in an EiffelIssueVerifiedEvent.
diff --git a/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md b/eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelSourceChangeCreatedEvent (SCC)
+
 The EiffelSourceChangeCreatedEvent declares that a change to sources has been made, but not yet submitted (see [EiffelSourceChangeSubmittedEvent](./EiffelSourceChangeSubmittedEvent.md)). This can be used to represent a change done on a private branch, undergoing review or made in a forked repository. Unlike EiffelSourceChangeSubmittedEvent, EiffelSourceChangeCreatedEvent _describes the change_ in terms of who authored it and which issues it addressed.
 
 Where changes are integrated (or "submitted") directly on a shared branch of interest (e.g. "master", "dev" or "mainline") both EiffelSourceChangeCreatedEvent and EiffelSourceChangeSubmittedEvent are sent together.
diff --git a/eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md b/eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelSourceChangeSubmittedEvent (SCS)
+
 The EiffelSourceChangeSubmittedEvent declares that a change has been integrated into to a shared source branch of interest (e.g. "master", "dev" or "mainline") as opposed to a private or local branch. Note that it does not describe what has changed, but instead uses the __CHANGE__ link type to reference [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md).
 
 Typical use cases for EiffelSourceChangeSubmittedEvent is to signal that a patch has passed code review and been submitted or that a feature/topic/team branch has been merged into the mainline/trunk/master. Where changes are made directly on the mainline, it is recommended to send both [EiffelSourceChangeCreatedEvent](./EiffelSourceChangeCreatedEvent.md) and EiffelSourceChangeSubmittedEvent together for information completeness.
diff --git a/eiffel-vocabulary/EiffelTestCaseCanceledEvent.md b/eiffel-vocabulary/EiffelTestCaseCanceledEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelTestCaseCanceledEvent (TCC)
+
 The EiffelTestCaseCanceledEvent declares that a previously triggered test case execution (represented by [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md)) has been canceled _before it has started_. This is typically used in queuing situations where a queued execution is dequeued. It is recommended that __CAUSE__ links be used to indicate the reason.
 
 ## Data Members
diff --git a/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md b/eiffel-vocabulary/EiffelTestCaseFinishedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelTestCaseFinishedEvent (TCF)
+
 The EiffelTestCaseFinishedEvent declares that a previously started test case (declared by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) has finished and reports the outcome.
 
 Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test case reports not only the conclusion of the test case execution - whether the test case was successfully executed - but also passes a verdict on the item under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included.
diff --git a/eiffel-vocabulary/EiffelTestCaseStartedEvent.md b/eiffel-vocabulary/EiffelTestCaseStartedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelTestCaseStartedEvent (TCS)
+
 The EiffelTestCaseStartedEvent declares that the execution of a test case has commenced. This event SHALL be preceded by a [EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md), and appropriately linked to via __TEST_CASE_EXECUTION__.
 
 ## Data Members
diff --git a/eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md b/eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelTestCaseTriggeredEvent (TCT)
+
 The EiffelTestCaseTriggeredEvent declares that the execution of a test case has been triggered, but not yet started. This can either be declared stand-alone or as part of an activity or test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively.
 
 This event is used to communicate intent, and thereby serves a similar purpose to that of [EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md). A triggered test case execution is expected to either be started (represented by [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) or canceled (represented by [EiffelTestCaseCanceledEvent](./EiffelTestCaseCanceledEvent.md)). Consequently, any delay between triggering and execution can be assumed to imply queuing time (e.g. waiting for available test resources) and monitored as such.
diff --git a/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md b/eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelTestExecutionRecipeCollectionCreatedEvent (TERCC)
+
 The EiffelTestExecutionRecipeCollectionCreatedEvent declares that a collection of test execution recipes has been created. In order to clarify what that means, several concepts need to be explained.
 
 Just as Eiffel is an opinionated protocol, EiffelTestExecutionRecipeCollectionCreatedEvent is an opinionated event, and to a certain extent that opinion goes against the grain of traditional test management. This event assumes that activity configurations and test scope definitions are two separate things. To exemplify, when one's CI server triggers the Acceptance Test activity in the pipeline, there is nothing in that activity that says which tests to execute where or with what parameters: that is a separate concern. Instead, it will query a test selection service for that information. This information is encapsulated by the EiffelTestExecutionRecipeCollectionCreatedEvent, which contains all the information needed to configure and execute the tests.
diff --git a/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md b/eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelTestSuiteFinishedEvent (TSF)
+
 The EiffelTestSuiteFinishedEvent declares that a previously started test suite (declared by [EiffelTestSuiteStartedEvent](./EiffelTestSuiteStartedEvent.md)) has finished and reports the outcome.
 
 Note that while similar, the __data.outcome__ object is different from that of [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md). The outcome of the test suite reports not only the conclusion of the test suite execution - whether the tests were successfully executed - but also passes a verdict on the item or items under test. To highlight this conceptual difference, both __data.outcome.verdict__ and __data.outcome.conclusion__ are included.
diff --git a/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md b/eiffel-vocabulary/EiffelTestSuiteStartedEvent.md
@@ -4,6 +4,7 @@
 --->
 
 # EiffelTestSuiteStartedEvent (TSS)
+
 The EiffelTestSuiteStartedEvent declares that the execution of a test suite has started. This can either be declared stand-alone or as part of an activity or other test suite, using either a __CAUSE__ or a __CONTEXT__ link type, respectively.
 
 In Eiffel, a test suite is nothing more or less than a collection of test case executions (see [EiffelTestCaseStartedEvent](./EiffelTestCaseStartedEvent.md)) and/or other test suite executions. The executed test suite may be an ad-hoc transient grouping of test cases that were executed at a particular time or place or for a particular purpose or a persistent entity tracked in a test management system - Eiffel makes no distinction or assumptions either way.
diff --git a/event_docs.md.j2 b/event_docs.md.j2
@@ -4,6 +4,10 @@
 --->
 
 # {{ type }} ({{ abbrev }})
+{%- if version.startswith('0.') %}
+> :warning: This event type is currently at version {{ version }} and is therefore experimental. Until it has reached version 1.0.0 it may undergo any number of backwards incompatible changes. It might also be deprecated and never reach 1.0.0.
+{%- endif %}
+
 {{ description }}
 
 ## Data Members
@@ -30,7 +34,7 @@ This section describes which link types are valid for this event type. For detai
 __Required:__ {{ link_data.required | yes_or_no }}  
 __Legal targets:__ {% if link_data.targets.any_type %}Any{% else %}{% for target_type in link_data.targets.types %}{{ target_type | event_link }}{{ ", " if not loop.last else "" }}{% endfor %}{% endif %}  
 __Multiple allowed:__ {{ link_data.multiple | yes_or_no }}  
-__Description:__ {{ link_data.description }}
+__Description:__ {{ link_data.description }}{% if link_data.experimental %} This link type targets an experimental event and may be removed in a future version of this event (see [Versioning](../eiffel-syntax-and-usage/versioning.md) for details).{% endif %}
 {%- endfor %}
 
 ## Meta Members
