From e72d305c0d4238d4547bd56bc6a73ad6876252bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20B=C3=A4ck?= Date: Thu, 15 Dec 2022 22:42:56 +0100 Subject: [PATCH 1/4] Add support for experimental event versions Document how experimental event versions work and add words of caution in a couple of places in the documentation template. --- eiffel-syntax-and-usage/event-schemas.md | 1 + eiffel-syntax-and-usage/versioning.md | 5 +++++ eiffel-vocabulary/EiffelActivityCanceledEvent.md | 1 + eiffel-vocabulary/EiffelActivityFinishedEvent.md | 1 + eiffel-vocabulary/EiffelActivityStartedEvent.md | 1 + eiffel-vocabulary/EiffelActivityTriggeredEvent.md | 1 + eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md | 1 + eiffel-vocabulary/EiffelArtifactCreatedEvent.md | 1 + eiffel-vocabulary/EiffelArtifactPublishedEvent.md | 1 + eiffel-vocabulary/EiffelArtifactReusedEvent.md | 1 + eiffel-vocabulary/EiffelCompositionDefinedEvent.md | 1 + eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md | 1 + eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md | 1 + eiffel-vocabulary/EiffelFlowContextDefinedEvent.md | 1 + eiffel-vocabulary/EiffelIssueDefinedEvent.md | 1 + eiffel-vocabulary/EiffelIssueVerifiedEvent.md | 1 + eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md | 1 + eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md | 1 + eiffel-vocabulary/EiffelTestCaseCanceledEvent.md | 1 + eiffel-vocabulary/EiffelTestCaseFinishedEvent.md | 1 + eiffel-vocabulary/EiffelTestCaseStartedEvent.md | 1 + eiffel-vocabulary/EiffelTestCaseTriggeredEvent.md | 1 + .../EiffelTestExecutionRecipeCollectionCreatedEvent.md | 1 + eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md | 1 + eiffel-vocabulary/EiffelTestSuiteStartedEvent.md | 1 + event_docs.md.j2 | 6 +++++- 26 files changed, 34 insertions(+), 1 deletion(-) diff --git a/eiffel-syntax-and-usage/event-schemas.md b/eiffel-syntax-and-usage/event-schemas.md index 792808dc..5a1865f8 100644 --- 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..description` | A description of the link type. | | `_links..required` | A boolean value indicating whether a link of this type is required. Optional, default false. | | `_links..multiple` | A boolean value indicating whether multiple links of this type is allowed. Optional, default false. | +| `_links..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..targets.any_type` | A boolean value indicating whether the link can point to an event of any type. | | `_links..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 index e47a752e..9ec47bdf 100644 --- 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 `-`. 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 index 19228675..45522dc2 100644 --- 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 index 16a72401..708ef346 100644 --- 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 index 040cdde0..3cf6d44f 100644 --- 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 index a57abbba..14b3ca23 100644 --- 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 index f7077f48..727229d9 100644 --- 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 index 3629c704..c4f2fb25 100644 --- 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 index 55ecb665..c7811e58 100644 --- 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 index 6c4a918f..962bb6b3 100644 --- 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 index 54d806c3..949dcbd8 100644 --- 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 index c292483d..4f017e4d 100644 --- 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 index 9b6876df..6bc18372 100644 --- 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 index 02a2f723..76b0be2d 100644 --- 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 index 8a7e4273..e4c33131 100644 --- 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 index 0c8b4d6c..3e719ebd 100644 --- 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 index 7262efbe..cc4efb2a 100644 --- 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 index 76a565a9..c55a2a5e 100644 --- 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 index d306f13e..6ca5ecfe 100644 --- 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 index f4577639..5d545271 100644 --- 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 index 8790400a..6090e24a 100644 --- 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 index d9065ebd..78c36861 100644 --- 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 index 4db9146d..f3baf09a 100644 --- 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 index 3197403a..45441194 100644 --- 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 index fd46263e..690df6a4 100644 --- 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 index dea7bc23..3eadef95 100644 --- 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 incomptaible 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 is experimental and may be removed in a future version of the event.{% endif %} {%- endfor %} ## Meta Members From c8fffc585cfc4462a4c28e9dc0d070d62fa8450b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20B=C3=A4ck?= Date: Thu, 22 Dec 2022 21:51:09 +0100 Subject: [PATCH 2/4] Fix typo --- event_docs.md.j2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event_docs.md.j2 b/event_docs.md.j2 index 3eadef95..bc4f275e 100644 --- a/event_docs.md.j2 +++ b/event_docs.md.j2 @@ -5,7 +5,7 @@ # {{ 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 incomptaible changes. It might also be deprecated and never reach 1.0.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 }} From 7665c850b7356167f39164bb52c25f456f60c322 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20B=C3=A4ck?= Date: Tue, 10 Jan 2023 17:24:36 +0100 Subject: [PATCH 3/4] It's the target event type that's experimental, not the link type MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Emil Bäckmark --- event_docs.md.j2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event_docs.md.j2 b/event_docs.md.j2 index bc4f275e..a01ffc74 100644 --- a/event_docs.md.j2 +++ b/event_docs.md.j2 @@ -34,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 }}{% if link_data.experimental %} This link type is experimental and may be removed in a future version of the event.{% endif %} +__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.{% endif %} {%- endfor %} ## Meta Members From 565a676c5bf3051965c9071b96a87d05e799e33c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Magnus=20B=C3=A4ck?= Date: Tue, 31 Jan 2023 22:23:52 +0100 Subject: [PATCH 4/4] Link to versioning.md in experimental link type docs --- event_docs.md.j2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/event_docs.md.j2 b/event_docs.md.j2 index a01ffc74..269870f9 100644 --- a/event_docs.md.j2 +++ b/event_docs.md.j2 @@ -34,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 }}{% if link_data.experimental %} This link type targets an experimental event and may be removed in a future version of this event.{% endif %} +__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