How to notify delivery of products delivered as source code?

[e-backmark-ericsson]

Description

There are cases where no explicit artifact is built when a product is delivered. I lack a way to describe that using Eiffel events. This happens for example when a product is delivered as a Git submodule into another product. There is no build or packaging going on in that submodule product, apart from probably setting a tag in the corresponding Git repository. How could we handle such a case?

One suggestion could be to notify this delivery using an ArtC event, where the identity field would point to a tag in the SCM system, for example: pkg:gerrit/path/to/repo/reponame@1.3.4. Providing an ArtP event for this would not be relevant since all info is already contained withing the ArtC event. The CD event to be used to link this ArtC event to the SCS will be dummy, since it would only be there to fulfill the allowed link types.

It feels a bit awkward to notify this SCM tagging using an ArtC event. Should we instead invent a new event for this use case?

If no change to the protocol is suggested, we should at least provide an event chain example to show how this could be done.

Motivation

Lacking event type or usage example

Exemplification

There is a need to notify that a source code product is delivered.

Benefits

As described above

Possible Drawbacks

If ArtC is to be used for this use case the term 'artifact' will get a slightly new meaning.

[magnusbaeck]

So you're concerned with the delivery notification, i.e. how should the parent git know when there's a new submodule commit to take into consideration for inclusion? Wouldn't a regular SCS be enough? Or is it the tagging operation itself you want to capture, if only tagged commits are subject to inclusion?

We make heavy use of source code delivery via tagged commits and my recent whiteboard sketch to model our pipeline makes use of a CD event with the name attribute set to the repository name and the version attribute set to the tag name. That event has a single ELEMENT link to either another CD element (if the git contains other gits, let's say via submodules) or to the SCS event representing the commit pointed to by the tag. Maybe using a CD event's name and version attributes like this is abuse?

As neither ArtC nor CD models the scenario I think a new event type is warranted. To avoid tool-specific terminology perhaps "alias" would work? After all, a tag or label is just an alternate name of an existing entity. EiffelSourceChangeAliasDefinedEvent (SCAD), with a mandatory name attribute and a mandatory (singular) link to an SCS? I'd expect most events that may link to SCS to also be able to link to SCAD.

[magnusbaeck]

Thinking about this some more, I'm not sure our scenario is entirely helped by SCAD. Simplified, our system is defined by a git containing references to tagged commits in other gits (let's say they're submodules). This can be represented by a CD with ELEMENT links to the SCSes (or SCADs) of the submodules and a CAUSE link to the SCS of the parent git, i.e. a change in the parent git forces the creation of a CD and is thus the cause of it (there should probably also be an ELEMENT link to the parent git SCS). So far so good, I think.

But what if the parent git gets tagged and this should serve as a trigger for further actions? That tag operation would create a SCAD pointing to the parent git's SCS, but you can't navigate from that event to the CD which contains the useful information since the links go in the opposite direction. Or am I wrong in expecting that you should be able to obtain all relevant events with a single-pass traversal of the event graph? I'll make some ASCII art to show what I mean:

                               Parent SCAD  --ALIAS-FOR-->  Parent SCS
                                                               ^
                                                               | CAUSE
                                                               |
Submodule SCS  <--ALIAS-FOR-- Submodule SCAD  <-----ELEMENT--  CD
                                                  |
Submodule SCS  <--ALIAS-FOR-- Submodule SCAD  <--/

So in this case the CD event itself might not be a reason to trigger other activity but the SCAD event is, so a consumer that wants to trigger a build from a tagged composition would have to

1. receive SCAD,
2. resolve to SCS,
3. look up CD with SCS as cause, and
4. trigger build.

If we want to achieve single-pass traversal I suppose the SCAD could trigger another the creation of another composition that points to the original composition but with a version set to the SCAD event's name.

[magnusbaeck]

Or could CD be used to express the tag creation, resulting in a one-element composition whose data.name attribute contains the SCM repository URL and data.version contains the tag?

[e-backmark-ericsson]

Interesting ideas! We're currently using ArtC to fulfill our needs of notifying that a tag has been created. We discussed using CD as well but ended up using ArtC as an intermediary solution. I'll digest this a bit more and come back when I've gathered my thoughts a bit more.

[magnusbaeck]

@e-backmark-ericsson, have you digested your thoughts on this matter? Or could you share how you're using ArtC to express tags?

[magnusbaeck]

The question above was resolved in a Slack thread. Copying the back-and-forth between me and @e-backmark-ericsson here for posterity:

• In a comment in [this issue] Emil Bäckmark mentions that Ericsson uses ArtC for expressing source control tags. Could someone provide more information on how you're modeling things? I note that ArtC doesn't allow linking to SCS so it's not immediately clear how you're linking these. Do you have an intermediate CD?
• Yes, we use an intermediate CD to link a 'source change' ArtC to SCS
• Thanks. And the reason for not using a CD directly and encoding the tag name (and possibly repo) in data.{name,version} is that the purl provides a more well-defined way of specifying git revisions?
• Yes, and because we use Eiffel Intelligence in some places to automatically notify our production machine when a new artifact has been created, regardless of if the 'artifact' is a built binary or a source change.

[sselberg]

Since source-code specification doesn't really fit within any currently existing event, why not define an event that fits? Suggestion: EiffelSourceCodeStateDefinedEvent with an immutable SCM identifier. For git it would look something like:

{
  "data": {
    "gitIdentifier": {
      "repoName": "my/project",
      "tag": "v3.3.2",
      "commitId": "39ed782..."
    }
  }
  "meta": {...}
  "links": {...}
}

[magnusbaeck]

We discussed this at the summit on 2023-06-13 and reached the conclusion that yes, please, we should have an event for tags. Use the recording at https://youtu.be/i8cFThy5-zc?t=5617 as reference.

[magnusbaeck]

This was discussed at the 2023-08-31 community meeting with the following conclusions:

• The new event should be called EiffelSourceStateLabelCreatedEvent with a single name field that describes the name of the tag. The event type name was deliberately chosen to be tool-agnostic.
• The event has a mandatory link named e.g. SOURCE_STATE that indicates the repository and commit that the tag refers to.
• An optional PREVIOUS_LABEL link can link to the semantically previous tag.
• We may want to add optional fields for the type of tag (with an implementation-specific value space, presumably) as well as the creator and submitter of the tag (similar to fields in SCS), but maybe those should be left out for 1.0.0.

[e-backmark-ericsson]

Given the recent discussions on #261, is the proposed name of this new event type (EiffelSourceStateLabelCreatedEvent) future-proof? Should we postpone solving this issue until the new source code events are finally declared?