Modeling Source Change Verdicts

definitions/EiffelConfidenceLevelModifiedEvent/4.1.0.yml

@@ -0,0 +1,208 @@
+# Copyright 2017-2025 Ericsson AB and others.
+# 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.
+---
+$schema: https://json-schema.org/draft/2020-12/schema#
+_name: EiffelConfidenceLevelModifiedEvent
+_version: 4.1.0
+_abbrev: CLM
+_description: |-
+  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.
+
+  See [Source Change Approval Using Confidence Levels](../eiffel-syntax-and-usage/clm-source-change-approved.md) for guidance on how to use the CLM event for reviews.
+type: object
+properties:
+  meta:
+    $ref: ../EiffelMetaProperty/4.0.1.yml
+  data:
+    type: object
+    properties:
+      name:
+        _description: The name of the confidence level. It is recommended
+          for confidence level names to conform with camelCase formatting,
+          in line with the format of key names of the Eiffel protocol
+          as a whole.
+        type: string
+      value:
+        _description: |-
+          The value of the confidence level.
+          SUCCESS signifies that the confidence level has been successfully achieved.  
+          FAILURE signifies that the confidence level could not be achieved.
+          INCONCLUSIVE signifies that achievement of the confidence level could not be determined.
+        type: string
+        enum:
+          - SUCCESS
+          - FAILURE
+          - INCONCLUSIVE
+      issuer:
+        _description: The individual or entity issuing the confidence
+          level.
+        type: object
+        properties:
+          name:
+            _description: The name of the issuer.
+            type: string
+          email:
+            _description: The e-mail address of the issuer.
+            type: string
+          id:
+            _description: Any identity, alias or handle of the issuer,
+              such as a corporate id or username.
+            type: string
+          group:
+            _description: Any group, such as a development team, committee
+              or test group, to which the issuer belongs.
+            type: string
+        additionalProperties: false
+      customData:
+        type: array
+        items:
+          $ref: ../EiffelCustomDataProperty/2.0.0.yml
+    required:
+      - name
+      - value
+    additionalProperties: false
+  links:
+    type: array
+    contains:
+      type: object
+      properties:
+        type:
+          enum:
+            - SUBJECT
+    items:
+      $ref: ../EiffelEventLink/2.0.0.yml
+required:
+  - meta
+  - data
+  - links
+additionalProperties: false
+_links:
+  CAUSE:
+    description: 'Identifies a cause of the event occurring. SHOULD
+      not be used in conjunction with __CONTEXT__: individual events
+      providing __CAUSE__ within a larger context gives rise to ambiguity.
+      It is instead recommended to let the root event of the context
+      declare __CAUSE__.'
+    required: false
+    multiple: true
+    targets:
+      any_type: true
+      types: []
+  CONFIDENCE_BASIS:
+    description: 'Used to declare the basis for which confidence statement(s) this event have used. 
+      The __CAUSE__ link tells what caused the event sending whereas __CONFIDENCE_BASIS__ declares the reason for
+      selecting the provided __data.name__ and/or __data.value__.'
+    required: false
+    multiple: true
+    targets:
+      any_type: false
+      types:
+        - EiffelConfidenceLevelModifiedEvent
+        - EiffelTestCaseFinishedEvent
+        - EiffelTestSuiteFinishedEvent
+  CONTEXT:
+    description: Identifies the activity or test suite of which this
+      event constitutes a part.
+    required: false
+    multiple: false
+    targets:
+      any_type: false
+      types:
+        - EiffelActivityTriggeredEvent
+        - EiffelTestSuiteStartedEvent
+  FLOW_CONTEXT:
+    description: 'Identifies the flow context of the event: which is
+      the continuous integration and delivery flow in which this occurred
+      – e.g. which product, project, track or version this is applicable
+      to.'
+    required: false
+    multiple: true
+    targets:
+      any_type: false
+      types:
+        - EiffelFlowContextDefinedEvent
+  PREDECESSOR:
+    description: 'Identifies which other CLM events this event supersedes. For example, in a scenario where CLM events signal reviews, this link indicates which earlies reviews became outdated due to this review.'
+    required: false
+    multiple: true
+    targets:
+      any_type: false
+      types:
+        - EiffelConfidenceLevelModifiedEvent
+  SUBJECT:
+    description: Identifies a subject of the confidence level; in other
+      words, what the confidence level applies to.
+    required: true
+    multiple: true
+    targets:
+      any_type: false
+      types:
+        - EiffelArtifactCreatedEvent
+        - EiffelArtifactDeployedEvent
+        - EiffelCompositionDefinedEvent
+        - EiffelSourceChangeCreatedEvent
+        - EiffelSourceChangeSubmittedEvent
+  SUB_CONFIDENCE_LEVEL:
+    description: 'Used in events summarizing multiple confidence levels.
+      Example use case: the confidence level "allTestsOk" summarizes
+      the confidence levels "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk",
+      and consequently links to them via __SUB_CONFIDENCE_LEVEL__.
+      This is intended for purely descriptive, rather than prescriptive,
+      use. Future editions might deprecate this link in favour of CONFIDENCE_BASIS.'
+    required: false
+    multiple: true
+    targets:
+      any_type: false
+      types:
+        - EiffelConfidenceLevelModifiedEvent
+_history:
+  - version: 4.1.0
+    changes: Add PREDECESSOR link (see [Issue 236](https://github.com/eiffel-community/eiffel/issues/236)).
+  - version: 4.0.1
+    changes: Detail the expected representation of public key and signature in meta.security  (see [Issue 375](https://github.com/eiffel-community/eiffel/issues/375)).
+  - version: 4.0.0
+    changes: Update meta schema to Draft 2020-12 and add link validation.
+  - version: 3.4.0
+    changes: Add CONFIDENCE_BASIS link (see [Issue 323](https://github.com/eiffel-community/eiffel/issues/323)).
+  - version: 3.3.0
+    introduced_in: edition-orizaba
+    changes: Add EiffelArtifactDeployedEvent as legal target type for
+      SUBJECT link (see
+      [Issue 239](https://github.com/eiffel-community/eiffel/issues/239)).
+  - version: 3.2.0
+    introduced_in: edition-arica
+    changes: Add schema URL to the meta object (see [Issue 280](https://github.com/eiffel-community/eiffel/issues/280)).
+  - version: 3.1.0
+    introduced_in: edition-lyon
+    changes: Add links.domainId member (see [Issue 233](https://github.com/eiffel-community/eiffel/issues/233)).
+  - version: 3.0.0
+    introduced_in: edition-agen
+    changes: Improved information integrity protection (see [Issue
+      185](https://github.com/eiffel-community/eiffel/issues/185)).
+  - version: 2.0.0
+    introduced_in: edition-agen
+    changes: Introduced purl identifiers instead of GAVs (see [Issue
+      182](https://github.com/eiffel-community/eiffel/issues/182))
+  - version: 1.1.0
+    introduced_in: edition-toulouse
+    changes: Multiple links of type FLOW_CONTEXT allowed.
+  - version: 1.0.0
+    introduced_in: edition-bordeaux
+    changes: Initial version.
+_examples:
+  - title: Simple example
+    url: ../examples/events/EiffelConfidenceLevelModifiedEvent/simple.json