Introduced purls instead of GAVs (#195)

Replaced GAVs for meta.source.serializer in all events, and for data.identity (instead of data.gav) and data.implements and data.dependsOn in EiffelArtifactCreatedEvent. Updated schema and examples accordingly. As part of that change, replaced .gliffy files (dependent on a specific tool) with .svg files (tool agnostic) and fixed some existing issues with the images. Replaced references to GAVs in compositions-and-validity-checking.md and confidence-level-joining.md. Also a typo was fixed in compositions-and-validity-checking.md.
eiffel-community · Sep 11, 2018 · dc5ec6f · dc5ec6f
1 parent 530690b
commit dc5ec6f
Show file tree

Hide file tree

Showing 87 changed files with 7,071 additions and 1,208 deletions.
diff --git a/eiffel-syntax-and-usage/compositions-and-validity-checking.md b/eiffel-syntax-and-usage/compositions-and-validity-checking.md
@@ -28,7 +28,7 @@ In this straight forward example, the integration of a system requires the prese
 
 Here composition C2 is legal, but C1 is not. The reason is that B1 requires version "[1.1.0,)" of com.example:a (that is, version 1.1.0 or later). In composition C1 there is no such artifact, but in composition C2 there is.
 
-Note that the [Maven version range syntax](http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html) is used to express version ranges.
+Note that the [Maven version range syntax](http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html) is used to express version ranges, but that these ranges are percent encoded as the version component of the [purl identity](https://github.com/package-url/purl-spec) (although for readability, the version ranges are not percent encoded in this documentation).
 
 ### Checking Backend Implementation Validity
 In this example we imagine a microservice setup. The service interface I has no implementation itself - instead it requires one or more implementations to which it can forward requests. There are multiple versions of the interface included, affording clients backwards compatibility.
@@ -39,12 +39,12 @@ Composition C1 is not valid: it contains two instances of A, one of I1 and one o
 
 Composition C2, on the other hand, is valid. It also contains two instances of A, but also one instance of B, which implements I from version 1.0.0 up to 3.0.0. Consequently, in this composition I1 has three artifacts implementing it, while I2 has one.
 
-### GAV vs event links
+### Purl vs event links
 Wherever feasible, the Eiffel framework promotes the usage of event references to link to other artifacts. It may seem like a reasonable option to use event links to declare dependencies, as well.
 
-The pragmatic reason for using GAVs (short for [groupId, artifactId and version](https://maven.apache.org/guides/mini/guide-naming-conventions.html)) in this particular case is version ranges: with event links there is no practical way of declaring ranges.
+The pragmatic reason for using (adapted) [purl identities](https://github.com/package-url/purl-spec) in this particular case is version ranges: with event links there is no practical way of declaring ranges.
 
-There is also a conceptual reason why event links are not suitable, however. Event links are consistently used to reference historical engineering artifacts - things that have been created and exist. Dependency declarations - particularly dependencies on version ranges - are much more intangible in nature. They do not simply provide a description of something that ought to be present. For this reason they can not be used as trace links, and are unsuitable for event reference representation.
+There is also a conceptual reason why event links are not suitable, however. Event links are consistently used to reference historical engineering artifacts - things that have been created and exist. Dependency declarations - particularly dependencies on version ranges - are much more intangible in nature. They simply provide a description of something that ought to be present. For this reason they can not be used as trace links, and are unsuitable for event reference representation.
 
 ### Additional Notes
 _Isn't this a reinvention of the wheel?_ you may ask. After all, there are plenty of tools that excel in handling dependency graphs. This is true, and the Eiffel dependency definition syntax is heavily influenced not least by [Maven](http://maven.apache.org). Eiffel operates at a highly technology and context agnostic level of abstraction, however, covering e.g. projects with highly diversified technology stacks and/or projects near or crossing over into hardware. This has both limitations and benefits. An Eiffel composition check can never guarantee that a given composition will work; what it can tell you is whether it is obviously broken.

diff --git a/eiffel-vocabulary/EiffelActivityCanceledEvent.md b/eiffel-vocabulary/EiffelActivityCanceledEvent.md
@@ -106,28 +106,10 @@ __Required:__ No
 __Description:__ The name of the event sender.
 
 #### meta.source.serializer
-__Type:__ Object  
-__Format:__   
-__Required:__ No  
-__Description:__ The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) coordinates of the serializer software used to construct the event.
-
-##### meta.source.serializer.groupId
-__Type:__ String  
-__Format:__ groupId  
-__Required:__ Yes  
-__Description:__ The groupId of the serializer software.
-
-##### meta.source.serializer.artifactId
 __Type:__ String  
-__Format:__ artifactId  
-__Required:__ Yes  
-__Description:__ The artifactId of the serializer software.
-
-##### meta.source.serializer.version
-__Type:__ String  
-__Format:__ version  
-__Required:__ Yes  
-__Description:__ The version of the serializer software.
+__Format:__ [purl specification](https://github.com/package-url/purl-spec)  
+__Required:__ No  
+__Description:__ The identity of the serializer software used to construct the event, in [purl format](https://github.com/package-url/purl-spec).
 
 #### meta.source.uri
 __Type:__ String  
@@ -162,6 +144,7 @@ __Description:__ The encrypted digest. The cryptographic hash function and the d
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
+| 2.0.0     | Current version                                        | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
 | 1.1.0     | [edition-toulouse](../../../tree/edition-toulouse)     | Multiple links of type FLOW_CONTEXT allowed. |
 | 1.0.0     | [edition-bordeaux](../../../tree/edition-bordeaux)     | Initial version.                        |
 

diff --git a/eiffel-vocabulary/EiffelActivityFinishedEvent.md b/eiffel-vocabulary/EiffelActivityFinishedEvent.md
@@ -138,28 +138,10 @@ __Required:__ No
 __Description:__ The name of the event sender.
 
 #### meta.source.serializer
-__Type:__ Object  
-__Format:__   
-__Required:__ No  
-__Description:__ The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) coordinates of the serializer software used to construct the event.
-
-##### meta.source.serializer.groupId
-__Type:__ String  
-__Format:__ groupId  
-__Required:__ Yes  
-__Description:__ The groupId of the serializer software.
-
-##### meta.source.serializer.artifactId
 __Type:__ String  
-__Format:__ artifactId  
-__Required:__ Yes  
-__Description:__ The artifactId of the serializer software.
-
-##### meta.source.serializer.version
-__Type:__ String  
-__Format:__ version  
-__Required:__ Yes  
-__Description:__ The version of the serializer software.
+__Format:__ [purl specification](https://github.com/package-url/purl-spec)  
+__Required:__ No  
+__Description:__ The identity of the serializer software used to construct the event, in [purl format](https://github.com/package-url/purl-spec).
 
 #### meta.source.uri
 __Type:__ String  
@@ -194,6 +176,7 @@ __Description:__ The encrypted digest. The cryptographic hash function and the d
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
+| 2.0.0     | Current version                                        | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
 | 1.1.0     | [edition-toulouse](../../../tree/edition-toulouse)     | Multiple links of type FLOW_CONTEXT allowed. |
 | 1.0.0     | [edition-bordeaux](../../../tree/edition-bordeaux)     | Initial version.                        |
 

diff --git a/eiffel-vocabulary/EiffelActivityStartedEvent.md b/eiffel-vocabulary/EiffelActivityStartedEvent.md
@@ -127,28 +127,10 @@ __Required:__ No
 __Description:__ The name of the event sender.
 
 #### meta.source.serializer
-__Type:__ Object  
-__Format:__   
-__Required:__ No  
-__Description:__ The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) coordinates of the serializer software used to construct the event.
-
-##### meta.source.serializer.groupId
-__Type:__ String  
-__Format:__ groupId  
-__Required:__ Yes  
-__Description:__ The groupId of the serializer software.
-
-##### meta.source.serializer.artifactId
 __Type:__ String  
-__Format:__ artifactId  
-__Required:__ Yes  
-__Description:__ The artifactId of the serializer software.
-
-##### meta.source.serializer.version
-__Type:__ String  
-__Format:__ version  
-__Required:__ Yes  
-__Description:__ The version of the serializer software.
+__Format:__ [purl specification](https://github.com/package-url/purl-spec)  
+__Required:__ No  
+__Description:__ The identity of the serializer software used to construct the event, in [purl format](https://github.com/package-url/purl-spec).
 
 #### meta.source.uri
 __Type:__ String  
@@ -183,6 +165,7 @@ __Description:__ The encrypted digest. The cryptographic hash function and the d
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
+| 2.0.0     | Current version                                        | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
 | 1.1.0     | [edition-toulouse](../../../tree/edition-toulouse)     | Multiple links of type FLOW_CONTEXT allowed. |
 | 1.0.0     | [edition-bordeaux](../../../tree/edition-bordeaux)     | Initial version.                        |
 

diff --git a/eiffel-vocabulary/EiffelActivityTriggeredEvent.md b/eiffel-vocabulary/EiffelActivityTriggeredEvent.md
@@ -134,28 +134,10 @@ __Required:__ No
 __Description:__ The name of the event sender.
 
 #### meta.source.serializer
-__Type:__ Object  
-__Format:__   
-__Required:__ No  
-__Description:__ The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) coordinates of the serializer software used to construct the event.
-
-##### meta.source.serializer.groupId
-__Type:__ String  
-__Format:__ groupId  
-__Required:__ Yes  
-__Description:__ The groupId of the serializer software.
-
-##### meta.source.serializer.artifactId
 __Type:__ String  
-__Format:__ artifactId  
-__Required:__ Yes  
-__Description:__ The artifactId of the serializer software.
-
-##### meta.source.serializer.version
-__Type:__ String  
-__Format:__ version  
-__Required:__ Yes  
-__Description:__ The version of the serializer software.
+__Format:__ [purl specification](https://github.com/package-url/purl-spec)  
+__Required:__ No  
+__Description:__ The identity of the serializer software used to construct the event, in [purl format](https://github.com/package-url/purl-spec).
 
 #### meta.source.uri
 __Type:__ String  
@@ -190,6 +172,7 @@ __Description:__ The encrypted digest. The cryptographic hash function and the d
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
+| 2.0.0     | Current version                                        | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
 | 1.1.0     | [edition-toulouse](../../../tree/edition-toulouse)     | Multiple links of type FLOW_CONTEXT allowed. |
 | 1.0.0     | [edition-bordeaux](../../../tree/edition-bordeaux)     | Initial version.                        |
 

diff --git a/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md b/eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md
@@ -122,28 +122,10 @@ __Required:__ No
 __Description:__ The name of the event sender.
 
 #### meta.source.serializer
-__Type:__ Object  
-__Format:__   
-__Required:__ No  
-__Description:__ The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) coordinates of the serializer software used to construct the event.
-
-##### meta.source.serializer.groupId
-__Type:__ String  
-__Format:__ groupId  
-__Required:__ Yes  
-__Description:__ The groupId of the serializer software.
-
-##### meta.source.serializer.artifactId
 __Type:__ String  
-__Format:__ artifactId  
-__Required:__ Yes  
-__Description:__ The artifactId of the serializer software.
-
-##### meta.source.serializer.version
-__Type:__ String  
-__Format:__ version  
-__Required:__ Yes  
-__Description:__ The version of the serializer software.
+__Format:__ [purl specification](https://github.com/package-url/purl-spec)  
+__Required:__ No  
+__Description:__ The identity of the serializer software used to construct the event, in [purl format](https://github.com/package-url/purl-spec).
 
 #### meta.source.uri
 __Type:__ String  
@@ -178,6 +160,7 @@ __Description:__ The encrypted digest. The cryptographic hash function and the d
 ## Version History
 | Version   | Introduced in                                          | Changes                                 |
 | --------- | ------------------------------------------------------ | --------------------------------------- |
+| 2.0.0     | Current version                                        | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
 | 1.1.0     | [edition-toulouse](../../../tree/edition-toulouse)     | Multiple links of type FLOW_CONTEXT allowed. |
 | 1.0.0     | [edition-bordeaux](../../../tree/edition-bordeaux)     | Initial version.                        |