Issue management support

[jaden-young]

Description

We propose creating new event types to handle issues as first class entities, and replacing the existing notion of issues in Eiffel with links to these new event types.

When EiffelSourceChangeCreatedEvent.data.issues was added, the status of issues made sense, as Eiffel is a protocol focused on CI/CD, not issue management. But the simultaneous existence of EiffelIssueVerifiedEvent.data.issues necessitates a refactoring.

This issue and pending pull request build on discussions in the Eiffel Community Google Group.

Changes can be summarized as follows:

New events

• EiffelIssueDefinedEvent: Gives provenance for an issue, serves as a handle for future links similar to EiffelActivityTriggeredEvent
  • Has the same type, tracker, id, and uri fields from EiffelSourceChangeCreatedEvent, as well as an optional title or summary.
• EiffelIssueStatusModifiedEvent: Used to transition the state of an issue: OPEN, RESOLVED, etc, links back to IssueDefined.
• EiffelIssueAssignedEvent (optional): Emitted when an issue is assigned to a contributor in an issue tracker, fields mirror EiffelSourceChangeCreatedEvent.data.author. This event could aid traceability to specific contributors, but introduces the same problem of two events referencing an entity without a canonical form.

Modifications to existing events

• EiffelSourceChangeCreatedEvent: Remove data.issues, replacing with new link types targeting IssueDefined:
  • data.issues.transition.PARTIAL -> PARTIALLY_RESOLVED_ISSUE
  • data.issues.transition.RESOLVED -> RESOLVED_ISSUE
  • data.issues.transition.REMOVED -> DERESOLVED_ISSUE
• EiffelIssueVerifiedEvent: Remove data.issues, replacing with new link types targeting IssueDefined:
  • data.issues.value.SUCCESS -> SUCCESSFUL_ISSUE
  • data.issues.value.FAILURE -> FAILED_ISSUE
  • data.issues.value.INCONCLUSIVE -> INCONCLUSIVE_ISSUE

Motivation

There are two main motivating factors to these changes. The first is that the current state of SourceChangeCreated and IssueVerified both containing an array of issues is not desirable. Two different events reference the same entity without a canonical form, inviting inconsistency as the protocol evolves. The second reason for these proposed protocol changes is to facilitate the creation of issue management plugins for Eiffel.

Exemplification

In the current version of Eiffel, connecting an IssueVerified to a SourceChangeCreated through an issue is rather difficult. There are no explicit links between them, and inferring a link proves computationally complex as one must query all events of each type and manually inspect the issues fields. In contrast, with issues as first class entities, in a situation such as:

IssueDefined <--RESOLVED_ISSUE---- SourceChangeCreated
             <--SUCCESSFUL_ISSUE-- IssueVerified       <--CAUSE--\
             <--ISSUE------------- IssueStatusUpdated  ----------/

The link between SourceChangeCreated and IssueVerified through the same Issue is simpler to follow through explicit links.

Benefits

Introducing new event types for issues allows for the integration of issue management plugins, improving traceability. Providing a canonical representation of issues also improves the robustness of Eiffel as a protocol by avoiding consistency issues between event types. As is mentioned in Eiffel documentation, often the true value of events lies in their relation to other events. Moving issues out of data members allows contributors to leverage Eiffel's links to inspect relationships.

Possible Drawbacks

It can be argued that to add issue management events is to add bloat, as Eiffel's stated purpose is in the context of CI/CD. However, as previously mentioned, issues already exist in the current version of Eiffel, and the community has expressed interest in plugins for JIRA or similar issue management software.

Removing data.issues from SCC and IV does have a significant consequence in that in order for SCC and IV to reference an issue it must already exist inside of Eiffel, which requires that an actor exist in the system already producing Eiffel events from that issue tracker.

[rogpers-ericsson]

In principle this makes sense, but as always the devil's in the details.

Another drawback, or perhaps a special case of the stated drawback in the description, is that whoever publishes EiffelSourceChangeCreatedEvent need to find the mapping from the "human" id of the issue and the internal event id of the corresponding event.

[jaden-young]

@rogpers-ericsson The drawback of needing to find the mapping from an external identifier to the UUID of an Eiffel event was mentioned in the first couple of messages in the Google Group discussions about a JIRA plugin. Ideally, this is where Remrem comes in.

Moving issues out of data and into links does increase immediate complexity for an implementation publishing SourceChangeCreated, but arguably has a net positive effect on the system as a whole. Principally this change ensures consistency with IssueVerified and future events that may reference issues, but it also enables consumers. In particular, it facilitates viewing an Eiffel event graph in terms bugs and features, especially as new events are added to the protocol. "What went into making this feature?" becomes much easier to answer when searching for a single UUID in links than drilling down into different paths of different events data for not necessarily consistent information.

At the end of the day it's a question of where complexity lives. Should producers rely on a service existing that can answer "here's a URI of an issue, what's the Eiffel UUID that corresponds to it?" Or should consumers that care about issues need to know which event types pertain to issues, know what data about issues they contain, know the shape of that data, require updates whenever any event pertaining to issues changes?

We think that the reduction in complexity for consumers is much greater than the increase in complexity for producers. A service such as Remrem, or at the very least query-able persistent storage, is bound to exist in a production Eiffel system.

[e-backmark-ericsson]

I like the idea of adding EiffelIssueDefinedEvent to make references from SCC and IV clearer.

Regarding the other two events I'm a bit worried. I assume your use case is that you want to trigger some activity when an Issue has changed status or has got a person assigned to it, right? What scares me is that these kind of events could start being used to look up the 'current' status or assignments of those issues. For such operations you should of course always go to the source ask the issue management system directly since it should of course always have the truth. Could you elaborate a bit more on the use cases of those events? So far the events in the Eiffel protocol are there to serve a Cx/DevOps pipeline and I'm not sure that these two events really fit there, do they?

If you omit the IssueStatusModified and IssueAssigned events from the Pull request I think it would come through a lot quicker.

[d-stahl-ericsson]

I closed it, but then realized that's premature. The merged PR (#188) only addresses a subset of this. Until we have sorted out #190 we need to keep this open.

[e-backmark-ericsson]

This issue was quickly discussed on an Eiffel Community meeting today. Our idea is to eventually provide an EiffelIssueModifiedEvent fulfilling the remaining needs in this issue. Would that be enough for your use case @jaden-young ?