JIRA Plugin?

[Ola Leifler]

Hi!

We are considering in what way it could make sense to create a JIRA plugin for Eiffel, and have had some questions from a group of students we have engaged in this. However, the protocol as is does not seem adapted to include issues and user stories in the Eiffel workflow as proper Eiffel events. If we use ArtifactCreatedEvent to denote issues being created in JIRA, that cannot readily be linked to SourceChangeCreatedEvent. The data.issues fields in a SourcechangeCreatedEvent link directly to JIRA or similar systems.

There is an "EiffelIssueVerifiedEvent", but no "EiffelIssuePostedEvent" or similar. Maybe we need one to explicitly work with issues and add them to the protocol?

/Ola

[Daniel Ståhl]

Hi!

It's certainly conceivable. I would recommend that you play around with the idea and what it would look like in a separate repository. On a similar note, some people who want to see the protocol extended into deployment and operations (which I wholeheartedly support) are doing just that in https://github.com/Ericsson/eiffel-operations-extension

From the top of my head, it seems to me like you would need at least one dedicated event to serve as issue provenance (e.g. EiffelIssueDefinedEvent or some such) and a dedicated link type, letting you do e.g. EiffelSourceChangeCreatedEvent -ISSUE-> EiffelIssueDefinedEvent.

When we have a concrete proposal we can try it out, and if we like it, we add it to the core vocabulary.

Daniel

[jaden....@gmail.com]

Hi!

I'm part of the team from North Dakota working on integrating issue management further into Eiffel. Our working ideas for vocabulary can be found at https://github.com/eiffel-community/eiffel-jira-plugin/tree/vocabulary/eiffel-vocabulary.

We're trying to find a place where we can provide a good amount of utility by upgrading issues to a first class event without throwing in the kitchen sink. While FlowContextDefined exists, we believe there is value in tracking additional information, as the FlowContext really only gives a single string as a possible data member, and issues represent an integral part of software development. Our current thinking is to create an IssueDefinedEvent as mentioned with a minimal amount of information: that which currently exists in SourceChangeCreated along with an optional title/summary of the issue. Additional data, such as resolution state or who the issue is assigned to, can be attached later through additional event types with an ISSUE link. This would allow the IssueDefinedEvent to be rather resilient to future protocol changes.

A possible path is to deprecate the "issues" fields of SourceChangeCreated and IssueVerified events in favor of ISSUE links. The "transition" field of SourceChangeCreated would also be deprecated, replaced by creating an IssueStatusUpdatedEvent with a -CAUSE-> SourceChangeCreated and -ISSUE-> IssueDefined. The "issue" with this path is that it requires source control plugins to be able to query some sort of persistent store of Eiffel events to populate the ISSUE link. The commit message parsing would still be possible, and equivalent information would still be emitted as Eiffel events, just in a different form. We also should consider the coupling of issue management and source control plugins, especially as it pertains to updating the status/state of issues, i.e. open/resolved. Our current thinking is to simply allow multiple IssueStatusUpdatedEvents, even when only one "logically" took place, letting duplicates serve simply as signals that the change is propagating throughout the system. That is, if an organization is running a plugin such as https://github.com/Praqma/commit-message-parser to parse commit messages, as well as running a plugin to receive Github or JIRA issue related webhook events, both would produce EiffelIssueStatusUpdated events.

We're open to feedback from the community on whether this is a worthwhile change, as well as any alternative paths.

NDSU Team

[Daniel Ståhl]

Hi!

Thank you for the suggestion! Indeed, FlowContext is a poor option for trying to tie things into individual issues - it's rather intended to identify e.g. a product, a project or something similar (letting me filter out everything that pertains to my-really-important-release-project). To represent issues, a specific event would be needed.

Actually, I would argue there's been a need for an IssueDefined ever since IssueVerified was introduced. Originally, only SourceChangeCreated would reference issues (using the data.issues array), but once IssueVerified was introduced we have two event types referencing an entity of which there is no canonical representation.

As for the details of the proposal:
- EiffelIssueStatusUpdatedEvent is an interesting idea. There are some caveats, however.

- A specific event describing a change in an issue is somewhat different from having an EiffelSourceChangeCreatedEvent state that it constitutes a fix to an issue. An EiffelIssueStatusUpdatedEvent would imply that the actual issue in the issue tracker (e.g. JIRA) has changed status. In other words, it's a stronger claim than what EiffelSourceChangeCreatedEvent.data.issues.transition is intended as. Which is not necessarily a bad thing, but...

- We should expect an event like EiffelIssueStatusUpdatedEvent to be emitted by the tracker itself. If you have other actors than the owner of the data emitting events as to changes in that data, you invite inconsistency and complicated dependencies. A cleaner solution - and in line with the intention of EiffelSourceChangeCreatedEvent.data.issues.transition - would be to introduce e.g. EiffelIssueAddressedEvent. This could be sent by anyone, such as an SCM system, saying "I have now addressed this issue, it should be fixed!", whereas EiffelIssueStatusUpdatedEvent would be used when it actually changes status in the tracker. In this scenario, a logical graph would look something like:

IssueDefined <--ISSUE-- IssueAddressed --CHANGE--> SourceChangeCreated
             <--ISSUE-- IssueVerified <--CAUSE--\
             <--ISSUE-- IssueStatusUpdated -----/

(Not sure if that bit of ASCII art makes sense, but...)

- Querying persistent storage is (almost) always a problem when generating events. This is where the Remrem service (ideally) comes in. Unfortunately it doesn't quite live up to that promise at the time of writing, but if the publisher of the event sends an identifying string to Remrem it should be able to look up the UUID to link to. Otherwise we'll have every actor in the ecosystem having to query persistent storage to serialize events, creating a lot of overhead.

[jaden.yo...@gmail.com]

Hi!

Thank you for the feedback. We were concerned about consistency with the EiffelIssueStatusUpdatedEvent, but were cautious of adding too many new events. Distinction of event type for data ownership does lead to a much cleaner solution. We'll post again with updated events.

On a somewhat tangential note, I haven't looked too deeply, but could this sort of consistency issue also come up in buildserver <--> SCM interaction? For example, Jenkins says EiffelTestSuiteFinishedEvent, but also tells bitbucket that a build passed through an existing integration. I'm not very familiar with existing apis, but would bitbucket also be capable of emitting the same event?

[Daniel Ståhl]

Hi,

I have to admit that I'm not a BitBucket user, but I in my world it occupies a similar space to e.g. GitHub. Unless I'm mistaken in that, I'm not sure I see a situation where it would make sense for BitBucket to send a TestSuiteFinishedEvent. Could you elaborate?

Best regards,
Daniel

[jaden.yo...@gmail.com]

Hi,

TestSuiteFinishedEvent was a poor choice of event, I was thinking more along the lines of the Activity events. For example, in GitHub, the status api is used by Travis/AppVeyor/etc. to show the build/test status of a commit. These updates are then in turn emitted by the GitHub webhook api. An Eiffel GitHub plugin would then have all information necessary to emit an ActivityTriggeredEvent, ActivityCanceledEvent, and ActivityFinishedEvent for each build of a commit without any need for a Travis plugin for Eiffel events, as ActivityFinished links to ActivityTriggered, not ActivityStarted. But in the case that there also exists a running Eiffel Travis plugin, Travis would be considered the owner of the data but possibly conflicting events could be emitted by both Travis and GitHub plugins.

This problem could in theory be solved by ensuring only one side emits Eiffel events, but I don't think this would work in practice. The onus would either be on the plugin developers or system administrators. Plugins restricting themselves to data they ostensibly own would result in a simpler system. But their functionality would be limited and a plugin must then exist for every discrete source of information, not to mention it would require a strong convention. In the GitHub/Travis/AppVeyor example, GitHub being able to emit the Activity events does have certain advantages. While the "queue time" data derived from the time delta between ActivityTriggered and ActivityStarted is lost, it also means fewer moving parts as it doesn't require an Eiffel plugin for each build service to be active and properly configured. Additionally, it would preserve information should one of the buildserver Eiffel plugins go down. As Eiffel is an open protocol with similarly open implementations, we can be confident that someone will do this. On the other hand, we could say that administrators should ensure that knobs are turned correctly for each plugin throughout the system such that no duplicate/conflicting events could be emitted, but that feels like a brittle solution. More generally, dictating the scope of plugins seems infeasible, and we should assume that "rebroadcast" data will exist in the system.

From what I can tell this isn't an isolated issue; there exist numerous integrations between build server <---> SCM <---> issue tracker, whatever the specific software may be, and in many cases existing non-Eiffel events in one space are rebroadcast in another. Heck, Slack may very well aggregate a good amount of information in many organizations' CI/CD pipelines already and an Eiffel Slack plugin could be capable of emitting all kinds of Eiffel events. Two possible solutions to the consistency problem come to mind if conflicting data exists. One path is first class events for data owners and second class events for the rest of the world, such as IssueStatusUpdated and IssueAddressed. Another is a single set of events, such as the current state of Activity events, but that the source of events be inspected to determine the reader's level of confidence in them.

IssueAddressed is claiming to the rest of the world "I've done something that should result in a mutation of another entity's data", and the GitHub status api would be saying "I claim that Travis told me his build succeeded." In one case it is a change that has already happened, in the other case it is a change that should happen in the future. Either way, from the perspective of the rest of the system, what is seen is "There's a change in someone else's data." Perhaps I'm generalizing too much, and the difference between issue management <--> SCM and SCM <--> build server are great enough to warrant different approaches.

I guess the question I'm asking comes down to this: Do we want to handle the consistency of Eiffel events consistently?

[Daniel Ståhl]

Hi,

Ok, now I'm with you. Thank you for bringing up the issue, it's a very relevant one.

Let me begin by saying that as a principle, questions such as these have been left deliberately unanswered from a strict protocol stand-point: who sends messages and how is a question of implementation architecture, of which there really is none. At least not explicitly stated, though there are some implicit hints which are derived from how we have done things internally in Ericsson. As interest in the project is clearly growing, and assuming that various plugins, services and other implementations begin to materialize in the open source domain, this is clearly a problem. So what do we do about that? I would really like to keep those concerns out of the protocol itself, but at the same time a shared architecture with some concrete technology choices would be very useful.

Here's one idea: let's create such an architectural description that defines a set of actual and potential services, how they communicate, and their division of responsibility. It would be an entity separate from the protocol, but implementing a specific edition of it. And to begin with it would have more abstract boxes than implemented ones, but that would also serve as a useful roadmap and a way in for people looking to contribute.

As for the actual point raised in your post: I don't think you're over-generalizing, it is a general concern. On the one hand, implementing message authoring, serialization and publishing in every possible end-point is a lot of work, especially when that can involve some heavy lifting in terms of looking up event UUIDs. Letting a smaller set of end-points act as "spokespersons" e.g. via more simplistic REST APIs is clearly less work, but opens up a host of non-trivial questions about division of responsibility and ownership of data. I don't see any really good solution to those questions - your suggestions of e.g. multiple sets of events is interesting, but I fear we'll just end up digging ourselves deeper into complexity. I would argue that the cleanest solution is to provide an equally simple REST API that can do all that heavy lifting, yet doesn't itself own any data or behave as an actor in the system in any way. Then you maintain a clean separation of responsibilities. Sure, in the example of Travis and GitHub, you would still need some extra functionality in Travis, as opposed to only in GitHub, but it could be equally simple as that which already notifies GitHub. The idea is for Remrem to be that service. As we discussed in a separate mail conversation, Remrem clearly isn't living up to that right now, but still.

To summarize, I believe there are two questions here.
First, how do we deal with this type of issues? I would recommend creating a shared open source implementation architecture that can also serve as a roadmap.
Second, how do we deal with this particular issue? I would argue that a Remrem serving its intended purpose would be the best way forward.

Looking forward to hearing your thoughts on this!

Best regards,
Daniel

[jaden.yo...@gmail.com]

Hi,

Thank you for the suggestions. Creating a shared architecture sounds interesting, and I think that would warrant its own post outside of this thread for further discussion.

Focusing on the the issue management protocol additions, I'm having difficulty reconciling

We should expect an event like EiffelIssueStatusUpdatedEvent to be emitted by the tracker itself. If you have other actors than the owner of the data emitting events as to changes in that data, you invite inconsistency and complicated dependencies. A cleaner solution - and in line with the intention of EiffelSourceChangeCreatedEvent.data.issues.transition - would be to introduce e.g. EiffelIssueAddressedEvent.

in the context of SCM <---> issue tracker, where the recommendation is enforcement by the protocol, with

...as a principle, questions such as these have been left deliberately unanswered from a strict protocol stand-point: who sends messages and how is a question of implementation architecture...

in regards to the Travis/GitHub example where the recommendation is creating an implementation architecture.

It seems to me that by introducing EiffelIssueAddressedEvent and insisting EiffelIssueStatusUpdatedEvent be emitted only by the tracker, we cause the protocol to answer the question of who sends which messages, but only for certain events, where previously it had not. This could leave implementors in a rather confused state with regards to who gets to send every other Eiffel event. While creating a reference architecture would give guidance to implementors, I'm cautious of the protocol relying on the behavior of that specific architecture; the hand shapes the tool and the tool shapes the hand.

From what I see currently, maintaining a consistent approach to consistency with the current events in the Eiffel protocol requires the exclusion of EiffelIssueAddressedEvent.

[Daniel Ståhl]

Hi,

Agreed, I'll create a separate thread for implementation architecture. Such an architecture could mean a lot of different things and look a lot of different ways, so let's bounce some ideas around as to how to design it.

You raise an important point, but I don't think there's cause for concern in this case. The protocol should absolutely not be aware of an implementation architecture or make implicit assumptions about it, just as it isn't aware of any service implementations. The dependency and awareness graph needs to be strictly one-dimensional:

Service Implementation A (Version X) -> Implementation Architecture B (Version Y) -> Eiffel Protocol (Edition Z)

(With the exception of the implementation architecture listing implementations as reference implementations and/or examples.)

This means that when speaking strictly from a protocol standpoint, one has to assume a certain "deliberate stupidity" in terms of how the events are used in practice. When I say that we should expect an event like EiffelIssueStatusUpdatedEvent to be emitted by the tracker, I'm carelessly switching context without explicitly flagging that - my apologies. That being said, an understanding of that pragmatic reality still has to inform the design of the protocol, or it will end up in pristine ivory tower theory-land, with little practical use. Essentially, the goal is to design a protocol that creates a space in which a conducive implementation can fit.

The mental exercise I try to perform to maintain that balance is to not deal with physical services or other implementations from the viewpoint of the protocol, but with information entities. In the case of issues, this means that the protocol has very little notion of there being an issue tracker (beyond e.g. EiffelSourceChangeCreatedEvent.data.change.tracker) as an independent entity. For all the protocol knows, every event may be emitted by a single mastermind monolith. What it does know, however, is that there is such a thing as an issue, and that there are claims that can be made about an issue's intrinsic state, and claims that can be made about things happening in relation to that issue.

Let's take an example. You have a lawn, which has various properties, one of them being its state of being neatly mowed or not. I can do things to your lawn, which may or may not alter those properties. In this simile, announcing that I have taken a lawnmower to your lawn (EiffelIssueAddressedEvent) is very different from saying that the lawn has the property of being satisfactorily mown (EiffelIssueStatusUpdatedEvent, or perhaps rather EiffelIssueStatusChangedEvent to be consistent with EiffelConfidenceLevelChangedEvent?). If everything works out as expected, it would make sense to expect one to follow from the other, but that's not guaranteed. Also, by maintaining that separation, you create a space where a separation of concerns can be made in the implementation, without requiring it. In fact, the protocol would let you use either one of the events without the other, depending on what you think you need to communicate (if all you care about is that status change, then just do that and don't bother about its cause, or the other way around).

This is very similar to how other events are defined. Think of the example of test events and EiffelConfidenceLevelModifiedEvents, for instance. Test events report the outcome of tests for a certain IUT in a certain ENVIRONMENT. In this sense they are similar to the proposed EiffelIssueAddressedEvent. This is very different, however, from drawing actual conclusions about the quality of the IUT, which is what EiffelConfidenceLevelModifiedEvent does (and in that it is similar to the proposed EiffelIssueStatusUpdated/ChangedEvent). That doesn't mean they can't be sent by the same physical entity, but it also allows for separation of concerns.

This turned out to be a longer post than I anticipated. I hope it doesn't just come across as ramblings, but actually makes some sense :) Looking forward to hearing your thoughts.

[Brendan Curran]

Hello everyone,

I am Brendan Curran and I'm with the North Dakota team. Our apologies for the inactivity over the last week we have been on Spring Break but now we're back and ready to get back in to it.

Below is the link to the updated proposed additions to the protocol. We have added to the vocabulary and we are curious if we should move to pull request.

https://github.com/jaden-young/eiffel

[Daniel Ståhl]

Hi!

I trust you had a great Spring Break :)

To my eyes the changes look good. A few quick reflections:
- The second paragraph in ID reads more like a motivation for a PR than as documentation for the event.
- IV and SCC will need to be updated accordingly.
- Schemas are needed.

If you would define an issue (pun intended) in the Eiffel repo and create a PR that would be great.

[Daniel Ståhl]

By the way, what is your proposal regarding the EiffelIssueAddressedEvent discussed above? The easiest would be to let SCC reference addressed issues via e.g. ADDRESSED_ISSUE, in other words keeping the current concept but replacing data.issues with links. This would serve the same purpose as EiffelIssueAddressedEvent. The reason to introduce a dedicated event would be if we have an m:n relationship (as with artifacts, compositions and elements), but I don't really see that in this case.

Thoughts?

Daniel

[Brendan Curran]

We agree that IssueAddressed would make more sense as a link. We see a mapping from scc.data.issues.transition["PARTIAL"] to a link of type ISSUE, and from scc.data.issues.transition['RESOLVED'] to a link of type ADDRESSED_ISSUE.

[Daniel Ståhl]

Going the linking route, there are two options for handling scc.data.issues.transition that I can see.

Either we keep an analogous property in the event body (e.g. data.issueTransition) which would then apply to all linked issues. This is a bit clunky, and would reduce the expressiveness (by simply assuming that all transitions are the same... which in my experience, they nearly always are, but still). Parsing the events you would need to both check the link and then check the event body to make sense of the semantics of the link, which I think is bad design.

The other is what you propose, with separate link types, which I think is a cleaner solution. We would need three link types, though, for the three legal values of scc.data.issues.transition. I would also prefer link types that clearly communicate their meaning. How about RESOLVED_ISSUE, PARTIALLY_RESOLVED_ISSUE and RETRACTED_ISSUE? The last one is tripping me up - the current wording (REMOVED) is unfortunate, as it gives the impression of removing an issue rather than removing its resolution/implementation. I'm struggling for something succinct to express that, and RETRACTED isn't much better. Perhaps UNRESOLVED_ISSUE, though that's not quite accurate, either. DERESOLVED_ISSUE, I guess, had there been such a word :)

The only problem with the second option is that we end up with a lot of link types. I can't really come up with a rational argument for why that would be a problem, though, beyond gut feeling and a vague idea of neatness...

[Brett Knecht]

As far as link type vs data member goes, it seems like the question we're asking is "Where does the information about the relationship between two events belong? In one event's data, or in the link between them?" It seems natural that it would go in the link, and since Eiffel events don't allow any additional fields besides "type" and "target" on link objects, the only option left to us is to introduce link types.

As for the naming of REMOVED/RETRACTED in SCC, if the intent is that "The previously resolved status is being removed/retracted," would REOPENED make sense?

We've also been considering the common usage of commit message parsing in SCC. We see a use case of referencing an issue in a commit message without wanting to make a claim to transition the state of that issue. What are your thoughts on a link of type ISSUE or REFERENCED_ISSUE?

Finally, this approach leaves IssueVerified in a rather peculiar position of having no data members (other than customData). data.issues would be pulled out into links of type SUCCESSFUL_ISSUE, FAILED_ISSUE, and INCONCLUSIVE_ISSUE to an IssueDefined, leaving "data" empty. We don't necessarily see a problem with this, but it does feel a bit odd.

[Daniel Ståhl]

As for the naming of REMOVED/RETRACTED in SCC, if the intent is that "The previously resolved status is being removed/retracted," would REOPENED make sense?

As this is information that pertains to the change, and not the issue, I think REOPENED sends the wrong message. REOPENED is something I might say about the issue, as a consequence of a change addressing it being reverted.
 

We've also been considering the common usage of commit message parsing in SCC. We see a use case of referencing an issue in a commit message without wanting to make a claim to transition the state of that issue. What are your thoughts on a link of type ISSUE or REFERENCED_ISSUE?

Just to be clear, whatever SCC says, it can never be a claim to transition the state of the issue itself. It can only claim to do things related to or affecting the issue (as in the above example). I see your point, though. A REFERENCED_ISSUE might also remove the need for PARTIALLY_RESOLVED (or similar). Now we're getting into changing existing functionality territory, though, so I'd like to do some sort of survey among existing user before committing anything, but as long as we stay in a speculative mode, something like RESOLVED_ISSUE, REFERENCED_ISSUE and DERESOLVED_ISSUE would seem to cover all use cases yet maintain (in my experience) sufficient clarity.
 

Finally, this approach leaves IssueVerified in a rather peculiar position of having no data members (other than customData). data.issues would be pulled out into links of type SUCCESSFUL_ISSUE, FAILED_ISSUE, and INCONCLUSIVE_ISSUE to an IssueDefined, leaving "data" empty. We don't necessarily see a problem with this, but it does feel a bit odd.

 Not a problem, and it wouldn't be the first. See ArtR: https://github.com/Ericsson/eiffel/blob/master/eiffel-vocabulary/EiffelArtifactReusedEvent.md