Make issues first class entities (#187) #188

jaden-young · 2018-04-10T05:06:01Z

Applicable Issues

Issue #187

Description of the Change

Description of change follows from the initial description found in issue #187 prior to any feedback from the Eiffel community.

Alternate Designs

A possible alternative to introducing new issue related events would be to use the existing EiffelFlowContextDefinedEvent. We decided to introduce new event types because we felt the information conveyable by a FlowContext wasn't sufficient. A uri would be necessary to uniquely identify an issue out side of Eiffel, and attaching other data such as tracker is very useful. Coercing these into a FlowContext doesn't fit.

Benefits

Same benefits as listed in the first comment of issue #187 prior to any feedback.

Possible Drawbacks

Same possible drawbacks as listed in the first comment of issue #187 prior to any feedback.

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: Jaden Young jaden.young@ndsu.edu

Removed second paragraph (#6)

See https://groups.google.com/d/msg/eiffel-community/AjaqrmfynjE/_FLS4pYXBgAJ

Closes #2

Closes #1

Closes #19

See https://groups.google.com/d/msg/eiffel-community/AjaqrmfynjE/_FLS4pYXBgAJ

Closes #2

Closes #1

e-backmark-ericsson · 2018-04-13T06:55:38Z

eiffel-vocabulary/EiffelIssueDefinedEvent.md

+external issue management software. This event provides provenance for an issue,
+and acts as a "handle" for future issue related events similarly to
+[EiffelActivityTriggeredEvent](./EiffelActivityTriggeredEvent.md) and
+[EiffelTestCaseTriggeredEvent](./EiffelTestCaseTriggeredEvent.md). It provides


I don't think it is fair to compare ID with ActT and TCT. The latter events represent that an operation is put in queue to be executed. I would propose you end the sentence after 'issue related events'. It is semantically quite similar to ED and FCD though.

The description could definitely use some clarification. ID is certainly
similar semantically to FCD/ED; an issue really is just a specific kind of
flow context with additional data attached. What motivated the comparison to
ActT/TCT was the inclusion of state intrinsic to the entity. If we think
about an issue being defined, work being done on an issue, and being
resolved, it's quite similar to ActT, ActS, and ActF. We could say that ID
puts an operation (resolve this) on a queue (backlog) to be executed (by a
human). However, the similarity to ActT/TCT is moot without events like ISM.

e-backmark-ericsson · 2018-04-13T07:36:52Z

eiffel-vocabulary/EiffelIssueDefinedEvent.md

+### data.type
+__Type:__ String  
+__Required:__ Yes  
+__Legal values:__ BUG, IMPROVEMENT, FEATURE, WORK_ITEM, REQUIREMENT, OTHER  


Should this really be mandatory? And what if the type is changed in the issue management system, how should that be handled? I'd propose 'initialType' or 'initialCategory' and make it free text. It's values can be enforced by implementation specific guidelines instead.

Eh, I just saw that we have called this 'type' in the current issue references and the legal values come from there. It's not your invention. Sorry :) Anyway, when we're now at it I still think this should not be mandatory and its values should be free text.

The type changing in the issue management system is a good point. Similar to ISM, it's an instance of the question "Should Eiffel care about modifications to an entity's data?" which in turn depends on "To what degree does Eiffel care about describing an entity, and when does Eiffel simply identify it?" The latter question is answered in other events, for example ED and SCC, but has yet to be decided for issue related events.

This also relates to the earlier discussion about the semantic similarities of ID to FCD/ED vs ActT/TCT. The closer towards the identification side ID goes, the more similar to FCD, the closer to the descriptive side the closer to ActT.

As far as the values of data.type being an enum or free form string, I assume that when you say "implementation specific guidelines" you're talking about using the vocabulary of the issue tracker as specified in data.tracker. I'm concerned that removing the structure here leaves a lot of utility on the table. While subtle, making this free form has a significant consequence for consumers: they need to be aware of every issue type of every issue management software they want to consume. At this point, there have been N producer plugins in production emitting events from those issue trackers into Eiffel, and now M consumers need to speak the language of each of those N issue trackers anyways, so we've arrived back at the N*M number of integrations problem. If our goal is to enable heterogeneous systems to work together I think that requires having a common vocabulary with defined semantics.

I agree that an Eiffel deployment needs to have a common vocabulary. I'm just not sure all of it needs to be defined in the protocol itself. In some parts it can be more convenient to define the legal values in guidelines/wrappers to be used within the company/deployment. I completely agree that we don't want different values on data.type from different issue trackers within the same company/deployment.

Couldn't that be said about basically anything, though? I'd like some unambiguous rules as to what gets to be defined in the protocol, and what is left to guidelines/wrappers in each deployment. Right now it's sort of a gradient where we end up at slightly different places along the axis with every judgment call we make.

Agreed. And that's a topic to discuss in another issue.
About this one, let's keep the type values there for now, since they are already part of the current events (IV and SCC). And that field is mandatory in those events too, so let's keep it mandatory for now.

e-backmark-ericsson · 2018-04-13T07:46:31Z

eiffel-vocabulary/EiffelIssueDefinedEvent.md

+to be a detailed description, as such information should be accessible by
+following __data.uri__.
+
+### data.initialCategory


See my comment on this field in the ISM event.
Furthermore, the description talks about 'state' but this field is called 'category'. I guess I would prefer 'initialState' here. 'category' is what I would use for the issue type instead...
Even further, do we really need this field when we have the initialStatus field below? Wouldn't initialCategory/initialState always be 'NEW' or possibly 'OPEN'? It couldn't be RESOLVED, could it? It comes down to the semantics of this event I guess. Should it be consumed as 'Hey, there is a new issue created, take a look!' or 'Yes, that is the existing issue I want to link to, give me its current details'

The naming of these fields is a little unwieldly. The idea behind the category/status divide on ISM was to have a closed set of "something that needs work", "something being worked on", and "something that doesn't need any more work" in category, and leave any specific subclasses of those up to status. This would give consumers a simple and well defined path to react to/filter on the high level changes in category without having to worry about the underlying issue management software but still allow the flexibility of having a custom status. "TODO", "DOING", and "DONE" would probably have been better choices for categories, but we didn't want to insinuate that we were forcing kanban style/terminology. The semantics of category relied a bit on the context of being inside of an IssueStatusModifiedEvent, so initalCategory sounds a bit funny in an ID. We were thinking of ID/ISM being closer to ActT/ActS, where an issue defined with a status/category would be emitted in Eiffel as ID immediately followed by ISM.

As for how the event should be consumed, while we should definitely keep consumers' needs in mind, I would be cautious of being perscriptive.

Since we're moving to get the refactoring of SCC/IV into ID done first, I've removed initalCategory/initalStatus as they don't really make much sense without ISM existing.

e-backmark-ericsson · 2018-04-13T08:42:21Z

eiffel-vocabulary/EiffelIssueVerifiedEvent.md

-__Required:__ Yes  
-__Description:__ The identity of the issue. This is tracker dependent - most trackers have their own issue naming schemes.
+## Links
+### SUCCESFUL_ISSUE


Should be 'SUCCESSFUL_ISSUE'

e-backmark-ericsson · 2018-04-13T08:43:05Z

eiffel-vocabulary/EiffelIssueVerifiedEvent.md

+__Required:__ No  
+__Legal targets:__ [EiffelIssueDefinedEvent](../eiffel-vocabulary/EiffelIssueDefinedEvent.md)  
+__Multiple allowed:__ No  
+__Description:__ Identifies an issue that has been succesfully verified.


Should be 'successfully'

jaden-young · 2018-04-16T04:12:46Z

I've removed ISM/IA from the PR. What remains is essentially pulling the fields from data.issues out of SCC/IV and into ID, and adding semantically equivalent links from SCC/IV to ID. There's also an added optional data.title field on ID as a nice-to-have for human consumption.

e-backmark-ericsson · 2018-04-16T06:49:45Z

examples/events/EiffelIssueVerifiedEvent/simple.json

    {
      "type": "ENVIRONMENT",
      "target": "aaaaaaaa-bbbb-5ccc-8ddd-eeeeeeeeeee4"
+    },


meta.version 2.0.0

The data.issues object should removed here.

e-backmark-ericsson · 2018-04-16T06:52:22Z

schemas/EiffelIssueVerifiedEvent/2.0.0.json

+        "version": {
+          "type": "string",
+          "enum": [ "1.1.1" ],
+          "default": "1.1.1"


e-backmark-ericsson · 2018-04-16T06:53:25Z

examples/events/EiffelSourceChangeCreatedEvent/simple.json

      "tracker": "GitHub",
      "details": "https://github.com/johndoe/myPrivateRepo/commit/fd090b60a4aedc5161da9c035a49b14a319829b4",
      "id": "42"
-    },


meta.version 2.0.0

e-backmark-ericsson · 2018-04-16T06:57:52Z

schemas/EiffelSourceChangeCreatedEvent/2.0.0.json

+        "version": {
+          "type": "string",
+          "enum": [ "1.1.1" ],
+          "default": "1.1.1"


e-backmark-ericsson · 2018-04-16T14:05:05Z

👍

d-stahl-ericsson · 2018-04-17T06:14:53Z

Making good progress! Will you propose the other events (EiffelIssueStatusModifiedEvent and EiffelIssueAssignedEvent) in this PR, too?

e-backmark-ericsson · 2018-04-17T06:27:56Z

I'd prefer that ISM and IA would come in a later PR. It it not as obvious to me that we want those events in the protocol. I would need to be convinced of the need of those additional events before I'd be happy to propose them being added.

d-stahl-ericsson · 2018-04-26T07:03:28Z

I don't see any more comments coming in, so let's move forward on this. Let's merge the new ID event and hold on other Issue events until we sort out #190 (anyone want to take a stab at this? - would be greatly appreciated, I'm rather strapped for time right now). We need a link from README.md to ID. Other than that, we should be good to go?

If you have any objections, speak now and so on...

d-stahl-ericsson · 2018-05-15T06:34:16Z

Ping @jaden-young. Would you be willing to add the README link so I can merge, or would you rather that I added it?

jaden-young · 2018-05-16T02:16:22Z

My apologies, the link has been added to the README.

jaden-young and others added 30 commits March 4, 2018 15:40

WIP: Vocabulary for Issue management

379ca05

Changed meaning of OPEN and ACTIVE

5dba581

Added description for IssueAssigned

9066292

Modified description of IssueDefined

b471188

Removed second paragraph (#6)

94a14a7

Merge pull request #7 from BCurran94/issue-6

8085e64

Removed second paragraph (#6)

Moved data.issues into links. (#4)

4e473fc

See https://groups.google.com/d/msg/eiffel-community/AjaqrmfynjE/_FLS4pYXBgAJ

Add version history to IDE. Closes #15

2633843

Added version history for ISM, Closes #13

8bbdfc9

Added version history for IA. Closes #14

826d680

Moved data.issues into links. (#4)

b729cef

Replace data.issues in IV with links (#5)

6ffa30c

Added jsonschema for ISM (#21)

b7b811d

Closes #2

Add simple example for EiffelIssueStatusModifiedEvent (#11)

aa77e2e

Added jsonschema for issue defined (#24)

94f302b

Closes #1

Move data.value into issue link types (#19)

23f3879

Closes #19

WIP: Vocabulary for Issue management

192a523

Changed meaning of OPEN and ACTIVE

e999e90

Added description for IssueAssigned

de0870b

Modified description of IssueDefined

ae8a419

Removed second paragraph (#6)

14707a8

Moved data.issues into links. (#4)

69f5911

See https://groups.google.com/d/msg/eiffel-community/AjaqrmfynjE/_FLS4pYXBgAJ

Add version history to IDE. Closes #15

bce1bd8

Added version history for ISM, Closes #13

a309b9f

Added version history for IA. Closes #14

44cee69

Moved data.issues into links. (#4)

bad0d5f

Replace data.issues in IV with links (#5)

6181219

Added jsonschema for ISM (#21)

3981ce0

Closes #2

Add simple example for EiffelIssueStatusModifiedEvent (#11)

c63a04f

Added jsonschema for issue defined (#24)

deb8092

Closes #1

Changed data.category to free form string

b05a955

e-backmark-ericsson reviewed Apr 13, 2018

View reviewed changes

jaden-young added 4 commits April 13, 2018 08:43

Fixed typos

3099871

Removed refs to ActT and TCT

75b2ff7

Removed initialStatus/initialCategory

bf8a6e9

Removed ISM/IA

d9e0486

e-backmark-ericsson reviewed Apr 16, 2018

View reviewed changes

jaden-young added 3 commits April 16, 2018 08:40

Bumped version to 2.0.0

281d3ad

Bumped version to 2.0.0

47e849c

Bumped version to 2.0.0

86b0c3c

d-stahl-ericsson mentioned this pull request Apr 18, 2018

Clear rules on version stepping are needed #189

Closed

Added link to ID in README

dba95e8

d-stahl-ericsson approved these changes May 16, 2018

View reviewed changes

d-stahl-ericsson merged commit 0706840 into eiffel-community:master May 16, 2018

d-stahl-ericsson mentioned this pull request May 16, 2018

Issue management support #187

Open

magnusbaeck added the protocol All protocol changes label Nov 21, 2022

Make issues first class entities (#187) #188

Make issues first class entities (#187) #188

Uh oh!

Conversation

jaden-young commented Apr 10, 2018

Applicable Issues

Description of the Change

Alternate Designs

Benefits

Possible Drawbacks

Sign-off

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaden-young Apr 16, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

e-backmark-ericsson Apr 13, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jaden-young commented Apr 16, 2018

Uh oh!

e-backmark-ericsson Apr 16, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

e-backmark-ericsson commented Apr 16, 2018

Uh oh!

d-stahl-ericsson commented Apr 17, 2018

Uh oh!

e-backmark-ericsson commented Apr 17, 2018

Uh oh!

d-stahl-ericsson commented Apr 26, 2018

Uh oh!

d-stahl-ericsson commented May 15, 2018

Uh oh!

jaden-young commented May 16, 2018

Uh oh!

Uh oh!

jaden-young Apr 16, 2018 •

edited

Loading

e-backmark-ericsson Apr 13, 2018 •

edited

Loading

e-backmark-ericsson Apr 16, 2018 •

edited

Loading