Introduced purls instead of GAVs #195

d-stahl-ericsson · 2018-08-07T11:19:01Z

Applicable Issues

Description of the Change

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. In doing so, realized that usage-examples/delivery-interface has not been updated since EiffelIssueDefinedEvent was introduced, and so fixed this.

Gliffy is rather old and poorly maintained. Converted the diagram source file from .gliffy to a draw.io .xml file.

Alternate Designs

purl is not the only game in town. There's also e.g. SWID, but practical applications do not abound. Nevertheless, if other standards arise I believe we are well equipped to integrate them in a flexible manner: by using "identity" as a property name we stay agnostic. The string, currently prefixed "pkg:" as per purl specification could then be used for other identification schemes in the future (e.g. SWID tags) by similarly prefixing a string format.

Benefits

This gets rid of rather awkward Maven legacy that has been around for way too long. Maven was the best standard we had to fall back on in the very early days, but now this tight coupling to Maven is a weakness that needs to be fixed.

Possible Drawbacks

purl might not turn out to be the future universal standard, but it's pragmatic and usable for a wide variety of packaging types already. If a clear "winner" materializes down the road, see above on flexibility.

Sign-off

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or

(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or

(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.

(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.

Signed-off-by: Daniel Ståhl [email protected]

e-backmark-ericsson · 2018-08-09T12:23:41Z

eiffel-vocabulary/EiffelArtifactCreatedEvent.md


 ### data.fileInformation
 __Type:__ Object[]  
 __Required:__ No  
-__Description:__ A list of the artifact file contents, following the standard established by [Apache Maven](https://maven.apache.org/pom.html).
+__Description:__ A list of the artifact file contents. This information is optional, and when included, MAY include a complete or incomplete list of contents. In other words, it may be used to highlight only particular files of interest, such as launcher binaries or other entry-points.


If I know my grammar correctly it should be '...optional and, when included, MAY include...'

Thanks! Fixed.

e-backmark-ericsson · 2018-08-09T12:24:37Z

eiffel-vocabulary/EiffelArtifactCreatedEvent.md

 __Type:__ String  
 __Required:__ Yes  
-__Description:__ The classifier of the file within the artifact. If none, an empty string shall be used.
+__Description:__ The name (including relative path from the root of the artifact) on syntax appropriate for the artifact packaging type.


typo: '... or syntax ...', right?

Nope. The name should be on appropriate syntax. It's not that the property contains names or syntax.

e-backmark-ericsson · 2018-08-09T12:29:40Z

eiffel-vocabulary/EiffelArtifactCreatedEvent.md

-__Type:__ String  
-__Required:__ Yes  
-__Description:__ The groupId of the dependency.
+__Description:__ An array of [purl identified](https://github.com/package-url/purl-spec) entities this artifact implements. The typical use case of this is to identify interfaces implemented by this artifact. Note that [version range notation](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) may be used for the version component of the package identity.


There seems to be no version range syntax defined in purl but what it states is that the version field should be percent-encoded. I guess we should then complement the Note in this section with that the given version range needs to be percent-encoded.

Right, I attempted to clarify this in the most recent commit.

e-backmark-ericsson · 2018-08-09T12:31:01Z

eiffel-vocabulary/EiffelArtifactCreatedEvent.md

-__Description:__ The version of the dependency. Note that [version range notation](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) is supported.
+__Format:__ [purl specification](https://github.com/package-url/purl-spec)  
+__Required:__ No  
+__Description:__ An array of [purl identified](https://github.com/package-url/purl-spec) entities this artifact depends on. Note that [version range notation](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) may be used for the version component of the package identity.


See comment on data.implements above

e-backmark-ericsson · 2018-08-09T12:54:45Z

I embrace this change (with the comments sorted out). Anyway, I think someone with more experience in managing Eiffel events in Maven heavy applications should have a say about potential drawbacks. @emichaf ?

And, about moving from Gliffy to draw.io. I guess it's a good switch, but I'd prefer that it was managed in a separate PR where all diagrams where converted at once.

d-stahl-ericsson · 2018-08-13T06:45:28Z

And, about moving from Gliffy to draw.io. I guess it's a good switch, but I'd prefer that it was managed in a separate PR where all diagrams where converted at once.

You're right, of course. I was simply being lazy. Once #199 is merged I'll rebase to that.

e-backmark-ericsson · 2018-08-13T07:27:18Z

I'm fine with the latest commit.

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. In doing so, realized that usage-examples/delivery-interface has not been updated since EiffelIssueDefinedEvent was introduced, and so fixed this. Gliffy is rather old and poorly maintained. Converted the diagram source file from .gliffy to a draw.io .xml file.

d-stahl-ericsson · 2018-08-17T08:08:26Z

Rebased and updated the delivery-interface.svg.

e-backmark-ericsson

Main conversation item should to be updated? It refers to draw.io file

These files still mention GAV:

eiffel-syntax-and-usage/compositions-and-validity-checking.md
usage-examples/confidence-level-joining.md

Version ranges need to be percent-encoded. The documentation is fine, but some examples need to be updated:

examples/events/ArtifactCreatedEvent/backend.json:implements
examples/events/ArtifactCreatedEvent/dependent.json:dependsOn: The version range should be percent-encoded
svg files as well, or should the ranges mentioned there be considered schematic? (composition-dependency-check-example.svg and composition-backend-implementation-example.svg)

This PR creates non-backwards compatible changes to all events. See issue #200. I'd like to see that that issue is closed before this PR is merged.

compositions-and-validity-checking.md and confidence-level-joining.md mentioned GAVs. These references have been replaced. Also a typo was fixed in compositions-and-validity-checking.md.

Made version ranges percent encoded in event examples. Added a note in compositions-and-validity-checking.md that version ranges are not percent encoded in the documentation, for readability reasons.

d-stahl-ericsson · 2018-08-21T06:17:39Z

Main conversation item should to be updated? It refers to draw.io file

Nah, that was true at the time. The eventual commit message will be different.

These files still mention GAV

Good catch! I grepped for GAV and found no further instances in the repo, apart from event version history.

Version ranges need to be percent-encoded. The documentation is fine, but some examples need to be updated

I fixed the examples and grepped for other instances of "dependsOn" and "implements" in the repo, but found none (except schemas). In the documentation I added a note that version ranges are not percent encoded for readability reasons.

This PR creates non-backwards compatible changes to all events. See issue #200. I'd like to see that that issue is closed before this PR is merged.

Fair enough.

e-backmark-ericsson

The changes look good to me.
Just waiting for #200 to be sorted out before merge.

d-stahl-ericsson · 2018-08-28T06:50:06Z

#189 and #200 have been addressed. Are we good to go?

e-backmark-ericsson · 2018-08-28T08:40:02Z

I'm glad you asked, and not merged right away :)
I will check with some people implementing services for the protocol to see if they would accept this change, since it affects the possibility to patch earlier versions/editions easily, and this specific change might not be rated very high in priority amongst them.

rogpers-ericsson · 2018-08-30T07:45:02Z

I approve the general move away from a Maven-centric view of artifacts.

If possible to get in before GA then this would be a replacement of the old method. If not, then the old solution should be deprecated (not removed) for some time, with the purl-approach being the preferred solution.

e-backmark-ericsson reviewed Aug 9, 2018

View reviewed changes

d-stahl-ericsson mentioned this pull request Aug 15, 2018

All .gliffy files replaced by .svg #199

Merged

d-stahl-ericsson added 3 commits August 17, 2018 10:00

Fixed GitHub PR review comments.

842e2b3

Brought event types to front in delivery-interface.svg.

78615a9

d-stahl-ericsson force-pushed the issue182 branch from 3be8452 to 78615a9 Compare August 17, 2018 08:04

Removed obsolete draw.io .xml diagram.

d79fc00

e-backmark-ericsson mentioned this pull request Aug 20, 2018

Could we allow minor changes to previous editions? #200

Closed

e-backmark-ericsson requested changes Aug 20, 2018

View reviewed changes

d-stahl-ericsson added 2 commits August 21, 2018 08:05

Removed GAV references in documentation

e31e59c

compositions-and-validity-checking.md and confidence-level-joining.md mentioned GAVs. These references have been replaced. Also a typo was fixed in compositions-and-validity-checking.md.

Fixed version range percent encoding in graphs and examples

ccc5814

Made version ranges percent encoded in event examples. Added a note in compositions-and-validity-checking.md that version ranges are not percent encoded in the documentation, for readability reasons.

e-backmark-ericsson reviewed Aug 22, 2018

View reviewed changes

d-stahl-ericsson merged commit dc5ec6f into eiffel-community:master Sep 11, 2018

d-stahl-ericsson mentioned this pull request Sep 11, 2018

Improved security support #197

Merged

magnusbaeck added protocol All protocol changes protocol-incompat Protocol changes that aren't backwards compatible labels Nov 18, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Introduced purls instead of GAVs #195

Introduced purls instead of GAVs #195

d-stahl-ericsson commented Aug 7, 2018 •

edited

Loading

e-backmark-ericsson Aug 9, 2018

d-stahl-ericsson Aug 13, 2018

e-backmark-ericsson Aug 9, 2018

d-stahl-ericsson Aug 13, 2018

e-backmark-ericsson Aug 13, 2018

e-backmark-ericsson Aug 9, 2018

d-stahl-ericsson Aug 13, 2018

e-backmark-ericsson Aug 9, 2018

d-stahl-ericsson Aug 13, 2018

e-backmark-ericsson commented Aug 9, 2018

d-stahl-ericsson commented Aug 13, 2018

e-backmark-ericsson commented Aug 13, 2018

d-stahl-ericsson commented Aug 17, 2018

e-backmark-ericsson left a comment

d-stahl-ericsson commented Aug 21, 2018

e-backmark-ericsson left a comment

d-stahl-ericsson commented Aug 28, 2018

e-backmark-ericsson commented Aug 28, 2018

rogpers-ericsson commented Aug 30, 2018

Introduced purls instead of GAVs #195

Introduced purls instead of GAVs #195

Conversation

d-stahl-ericsson commented Aug 7, 2018 • edited Loading

Applicable Issues

Description of the Change

Alternate Designs

Benefits

Possible Drawbacks

Sign-off

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

e-backmark-ericsson commented Aug 9, 2018

d-stahl-ericsson commented Aug 13, 2018

e-backmark-ericsson commented Aug 13, 2018

d-stahl-ericsson commented Aug 17, 2018

e-backmark-ericsson left a comment

Choose a reason for hiding this comment

d-stahl-ericsson commented Aug 21, 2018

e-backmark-ericsson left a comment

Choose a reason for hiding this comment

d-stahl-ericsson commented Aug 28, 2018

e-backmark-ericsson commented Aug 28, 2018

rogpers-ericsson commented Aug 30, 2018

d-stahl-ericsson commented Aug 7, 2018 •

edited

Loading