-
Notifications
You must be signed in to change notification settings - Fork 61
Make issues first class entities (#187) #188
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
d-stahl-ericsson
merged 56 commits into
eiffel-community:master
from
jaden-young:issue-related-events
May 16, 2018
Merged
Changes from all commits
Commits
Show all changes
56 commits
Select commit
Hold shift + click to select a range
379ca05
WIP: Vocabulary for Issue management
jaden-young 5dba581
Changed meaning of OPEN and ACTIVE
jaden-young 9066292
Added description for IssueAssigned
jaden-young b471188
Modified description of IssueDefined
jaden-young 94a14a7
Removed second paragraph (#6)
BCurran94 8085e64
Merge pull request #7 from BCurran94/issue-6
jaden-young 4e473fc
Moved data.issues into links. (#4)
jaden-young 2633843
Add version history to IDE. Closes #15
jaden-young 8bbdfc9
Added version history for ISM, Closes #13
jaden-young 826d680
Added version history for IA. Closes #14
jaden-young b729cef
Moved data.issues into links. (#4)
jaden-young 6ffa30c
Replace data.issues in IV with links (#5)
Brett-Knecht b7b811d
Added jsonschema for ISM (#21)
jaden-young aa77e2e
Add simple example for EiffelIssueStatusModifiedEvent (#11)
jaden-young 94f302b
Added jsonschema for issue defined (#24)
BrandonRudiselNDSU 23f3879
Move data.value into issue link types (#19)
Brett-Knecht 192a523
WIP: Vocabulary for Issue management
jaden-young e999e90
Changed meaning of OPEN and ACTIVE
jaden-young de0870b
Added description for IssueAssigned
jaden-young ae8a419
Modified description of IssueDefined
jaden-young 14707a8
Removed second paragraph (#6)
BCurran94 69f5911
Moved data.issues into links. (#4)
jaden-young bce1bd8
Add version history to IDE. Closes #15
jaden-young a309b9f
Added version history for ISM, Closes #13
jaden-young 44cee69
Added version history for IA. Closes #14
jaden-young bad0d5f
Moved data.issues into links. (#4)
jaden-young 6181219
Replace data.issues in IV with links (#5)
Brett-Knecht 3981ce0
Added jsonschema for ISM (#21)
jaden-young c63a04f
Add simple example for EiffelIssueStatusModifiedEvent (#11)
jaden-young deb8092
Added jsonschema for issue defined (#24)
BrandonRudiselNDSU 24a0c21
Move data.value into issue link types (#19)
Brett-Knecht 3ff605c
Merging changes resulting from rebase/revert conflicts
jaden-young 30b1c98
Issue link types reflect original issues.transition semantics (#27)
jaden-young f523e2a
Changed link type to reflect change in spec doc
jaden-young 7070763
Reset copyright to Ericsson
jaden-young 751351a
Add jsonschema and example for ID (#1) (#12)
BrandonRudiselNDSU e12f861
Add JSONSchema for IA (#3)
BCurran94 c451796
Removed trailing whitespace
jaden-young 1755667
Removed unneded file
jaden-young 445b33c
Add example of IA (#10)
BCurran94 95f6498
Replaced tabs with spaces
jaden-young 4ef4e4a
Renamed version 1.1.1 to 2.0.0
jaden-young 49f8af1
Elaborated on issue description
jaden-young bb76787
Added example clarifying DERESOLVED_ISSUE
jaden-young a0d5696
__must__ -> MUST, compy with IETF RFCs
jaden-young 2bcdd38
Added inital status and category to ID
jaden-young 39adacd
Removed misnamed/empty schema file
jaden-young b05a955
Changed `data.category` to free form string
jaden-young 3099871
Fixed typos
jaden-young 75b2ff7
Removed refs to ActT and TCT
jaden-young bf8a6e9
Removed initialStatus/initialCategory
jaden-young d9e0486
Removed ISM/IA
jaden-young 281d3ad
Bumped version to 2.0.0
jaden-young 47e849c
Bumped version to 2.0.0
jaden-young 86b0c3c
Bumped version to 2.0.0
jaden-young dba95e8
Added link to ID in README
jaden-young File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,247 @@ | ||
| <!--- | ||
| Copyright 2018 Jaden Young | ||
| For a full list of individual contributors, please see the commit history. | ||
|
|
||
| Licensed under the Apache License, Version 2.0 (the "License"); | ||
| you may not use this file except in compliance with the License. | ||
| You may obtain a copy of the License at | ||
|
|
||
| http://www.apache.org/licenses/LICENSE-2.0 | ||
|
|
||
| Unless required by applicable law or agreed to in writing, software | ||
| distributed under the License is distributed on an "AS IS" BASIS, | ||
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| See the License for the specific language governing permissions and | ||
| limitations under the License. | ||
| ---> | ||
|
|
||
| # EiffelIssueDefinedEvent (ID) | ||
| The EiffelIssueDefinedEvent declares that an issue has been created in some | ||
| external issue management software. ID is semantically similar to | ||
| [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md) | ||
| and [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md). | ||
|
|
||
| ## Data Members | ||
|
|
||
| ### data.type | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Legal values:__ BUG, IMPROVEMENT, FEATURE, WORK_ITEM, REQUIREMENT, OTHER | ||
| __Description:__ The type of issue. | ||
|
|
||
| ### data.tracker | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Description:__ The name of the issue tracker. This can unfortunately not be | ||
| standardized, and is therefore context sensitive: though some trackers and ALM | ||
| tools are more popular than others, an exhaustive enumeration is impossible, | ||
| particularly when considering company specific internal solutions. Consequently | ||
| one should not rely on the name as the primary method of retrieval, but rather | ||
| __data.uri__. __data.tracker__ together with __data.id__ | ||
| is still useful for analysis and traceability, however, as long as it can be | ||
| correctly interpreted. | ||
|
|
||
| ### data.id | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Description:__ The identity of the issue. This is tracker dependent - most | ||
| trackers have their own issue naming schemes. | ||
|
|
||
| ### data.uri | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Description:__ A URI that links to a document describing the issue in depth. | ||
|
|
||
| ### data.title | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ A one-line title or summary of the issue. This exists mostly | ||
| for human consumption, as "Implement widget X" is much more meaningful to a | ||
| human when viewing a graph of Eiffel events than "1302". This is not meant | ||
| to be a detailed description, as such information should be accessible by | ||
| following __data.uri__. | ||
|
|
||
| ## Links | ||
|
|
||
| ### CAUSE | ||
| __Required:__ No | ||
| __Legal targets:__ Any | ||
| __Multiple allowed:__ Yes | ||
| __Description:__ Identifies a cause of the event occurring. SHOULD not be | ||
| used in conjunction with __CONTEXT__: individual events providing __CAUSE__ | ||
| within a larger context gives rise to ambiguity. It is instead recommended to | ||
| let the root event of the context declare __CAUSE__. | ||
|
|
||
| ### CONTEXT | ||
| __Required:__ No | ||
| __Legal targets:__ | ||
| [EiffelActivityTriggeredEvent](../eiffel-vocabulary/EiffelActivityTriggeredEvent.md), | ||
| [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) | ||
| __Multiple allowed:__ No | ||
| __Description:__ Identifies the activity or test suite of which this event | ||
| constitutes a part. | ||
|
|
||
| ### FLOW_CONTEXT | ||
| __Required:__ No | ||
| __Legal targets:__ | ||
| [EiffelFlowContextDefinedEvent](./EiffelFlowContextDefinedEvent.md) | ||
| __Multiple allowed:__ No | ||
| __Description:__ Identifies the flow context of the event: which is the | ||
| continuous integration and delivery flow in which this occurred – e.g. which | ||
| product, project, track or version this is applicable to. | ||
|
|
||
| ## Meta Members | ||
| ### meta.id | ||
| __Type:__ String | ||
| __Format:__ [UUID](http://tools.ietf.org/html/rfc4122) | ||
| __Required:__ Yes | ||
| __Description:__ The unique identity of the event, generated at event | ||
| creation. | ||
|
|
||
| ### meta.type | ||
| __Type:__ String | ||
| __Format:__ An event type name | ||
| __Required:__ Yes | ||
| __Description:__ The type of event. This field is required by the recipient | ||
| of the event, as each event type has a specific meaning and a specific set of | ||
| members in the __data__ and __links__ objects. | ||
|
|
||
| ### meta.version | ||
| __Type:__ String | ||
| __Format:__ [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html) | ||
| __Required:__ Yes | ||
| __Description:__ The version of the event type. This field is required by the | ||
| recipient of the event to interpret the contents. Please see | ||
| [Versioning](../eiffel-syntax-and-usage/versioning.md) for more information. | ||
|
|
||
| ### meta.time | ||
| __Type:__ Integer | ||
| __Format:__ Milliseconds since epoch. | ||
| __Required:__ Yes | ||
| __Description:__ The event creation timestamp. | ||
|
|
||
| ### meta.tags | ||
| __Type:__ String[] | ||
| __Format:__ Free text | ||
| __Required:__ No | ||
| __Description:__ Any tags or keywords associated with the events, for | ||
| searchability purposes. | ||
|
|
||
| ### meta.source | ||
| __Type:__ Object | ||
| __Format:__ | ||
| __Required:__ No | ||
| __Description:__ A description of the source of the event. This object is | ||
| primarily for traceability purposes, and while optional, some form of | ||
| identification of the source is __HIGHLY RECOMMENDED__. It offers multiple | ||
| methods of identifying the source of the event, techniques which may be | ||
| select from based on the technology domain and needs in any particular use | ||
| case. | ||
|
|
||
| #### meta.source.domainId | ||
| __Type:__ String | ||
| __Format:__ Free text | ||
| __Required:__ No | ||
| __Description:__ Identifies the domain that produced an event. A domain is an | ||
| infrastructure topological concept, which may or may not corresponds to an | ||
| organization or product structures. A good example would be Java packages | ||
| notation, ex. com.mycompany.product.component or mycompany.site.division. | ||
| Also, keep in mind that all names are more or less prone to change. | ||
| Particularly, it is recommended to avoid organizational names or site names, | ||
| as organizations tend to be volatile and development is easily relocated. | ||
| Relatively speaking, product and component names tend to be more stable and | ||
| are therefore encouraged, while code names may be an option. You need to | ||
| decide what is the most sensible option in your case. | ||
|
|
||
| #### meta.source.host | ||
| __Type:__ String | ||
| __Format:__ Hostname | ||
| __Required:__ No | ||
| __Description:__ The hostname of the event sender. | ||
|
|
||
| #### meta.source.name | ||
| __Type:__ String | ||
| __Format:__ Free text | ||
| __Required:__ No | ||
| __Description:__ The name of the event sender. | ||
|
|
||
| #### meta.source.serializer | ||
| __Type:__ Object | ||
| __Format:__ | ||
| __Required:__ No | ||
| __Description:__ The | ||
| [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) | ||
| coordinates of the serializer software used to construct the event. | ||
|
|
||
| ##### meta.source.serializer.groupId | ||
| __Type:__ String | ||
| __Format:__ groupId | ||
| __Required:__ Yes | ||
| __Description:__ The groupId of the serializer software. | ||
|
|
||
| ##### meta.source.serializer.artifactId | ||
| __Type:__ String | ||
| __Format:__ artifactId | ||
| __Required:__ Yes | ||
| __Description:__ The artifactId of the serializer software. | ||
|
|
||
| ##### meta.source.serializer.version | ||
| __Type:__ String | ||
| __Format:__ version | ||
| __Required:__ Yes | ||
| __Description:__ The version of the serializer software. | ||
|
|
||
| #### meta.source.uri | ||
| __Type:__ String | ||
| __Format:__ URI | ||
| __Required:__ No | ||
| __Description:__ The URI of, related to or describing the event sender. | ||
|
|
||
| ### meta.security | ||
| __Type:__ Object | ||
| __Format:__ | ||
| __Required:__ No | ||
| __Description:__ An optional object for enclosing security related | ||
| information, particularly supporting data integrity. See | ||
| [Security](../eiffel-syntax-and-usage/security.md) for further information. | ||
|
|
||
| #### meta.security.sdm | ||
| __Type:__ Object | ||
| __Format:__ | ||
| __Required:__ No | ||
| __Description:__ An optional object for properties supporting the [Strong | ||
| Distribution Model](http://www.cryptnet.net/fdp/crypto/strong_distro.html). | ||
| Note that this only addressed the _integrity_ of the Eiffel event, not its | ||
| _confidentiality_ or _availability_. | ||
|
|
||
| ##### meta.security.sdm.authorIdentity | ||
| __Type:__ String | ||
| __Format:__ | ||
| __Required:__ Yes | ||
| __Description:__ The identity of the author of the event. This property is | ||
| intended to enable the recipient to look up the appropriate public key for | ||
| decrypting the digest and thereby verifying author identity and data | ||
| integrity. The format of the author identity varies depending on the key | ||
| infrastructure solution used. Note that this requires the presence of a | ||
| Trusted Authority (TA) which the recipient can query for the correct public | ||
| key. The identity and location of the TA must never be included in the event | ||
| itself, as this would compromise the security of the solution. | ||
|
|
||
| ##### meta.security.sdm.encryptedDigest | ||
| __Type:__ String | ||
| __Format:__ | ||
| __Required:__ Yes | ||
| __Description:__ The encrypted digest. The cryptographic hash function and | ||
| the decryption algorithm to use, similarly to the Trusted Authority (TA), | ||
| must be known to the recipient. Note that the digest of the entire event is | ||
| affected by the value of this property. For this reason the input to the hash | ||
| function SHALL be the entire event unaltered in all parts except for this | ||
| property, which SHALL be replaced by an empty string. | ||
|
|
||
| ## Version History | ||
| | Version | Introduced in | Changes | | ||
| | --------- | ------------------------------------------------------ | --------------------------------------- | | ||
| | 1.0.0 | Current version | Initial version | | ||
|
|
||
| ## Examples | ||
| * [Simple example](../examples/events/EiffelIssueDefinedEvent/simple.json) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.typebeing 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 indata.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.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.