Added EiffelSourceChangeCreatedEvent documentation. #15
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,195 @@ | ||
| # EiffelSourceChangeCreatedEvent | ||
| The EiffelSourceChangeCreatedEvent declares that a change to sources has been made, but not yet submitted (see [EiffelSourceChangeSubmittedEvent](./EiffelSourceChangeSubmittedEvent.md)). This can be used to represent a change done on a private branch, undergoing review or made in a forked repository. Unlike EiffelSourceChangeSubmittedEvent, EiffelSourceChangeCreatedEvent _describes the change_ in terms of who authored it and which issues it addressed. | ||
|
|
||
| Where changes are integrated (or "submitted") directly on a shared branch of interest (e.g. "master", "dev" or "mainline") both EiffelSourceChangeCreatedEvent and EiffelSourceChangeSubmittedEvent are sent together. | ||
|
|
||
| ## Data Members | ||
| ### data.author | ||
| __Type:__ Object | ||
| __Required:__ No | ||
| __Description:__ The author of the change. | ||
|
|
||
| #### data.author.name | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ The name of the author. | ||
|
|
||
| #### data.author.email | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ The email address of the author. | ||
|
|
||
| #### data.author.id | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ Any identity, username or alias of the author. | ||
|
|
||
| #### data.author.group | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ Any group or organization to which the contributor belongs. | ||
|
|
||
| ### data.change | ||
| __Type:__ Object | ||
| __Required:__ No | ||
| __Description:__ A summary of the change. | ||
|
|
||
| #### data.change.insertions | ||
| __Type:__ Integer | ||
| __Required:__ No | ||
| __Description:__ The number of inserted lines in the change. | ||
|
|
||
| #### data.change.deletions | ||
| __Type:__ Integer | ||
| __Required:__ No | ||
| __Description:__ The number of deleted lines in the change. | ||
|
|
||
| #### data.change.files | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ A URI to a list of files changed, on JSON String array format. | ||
|
|
||
| #### data.change.details | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ A URI to further details about the change. These details are not assumed to be on any standardized format, and may be intended for human and/or machine consumption. Examples include e.g. Gerrit patch set descriptions or GitHub commit pages. It is recommended to also include __data.change.tracker__ to provide a hint as to the nature of the linked details. | ||
|
|
||
| #### data.change.tracker | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ The name of the tracker, if any, of the change. Examples include e.g. Gerrit or GitHub. | ||
|
|
||
| #### data.change.id | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ The unique identity, if any, of the change (apart from what is expressed in the identifier object). Examples include e.g. Gerrit Change-Ids or GitHub Pull Requests. It is recommended to also include __data.change.tracker__ to provide a hint as to the nature of the identity. | ||
|
|
||
| ### data.issues | ||
| __Type:__ Object[] | ||
| __Required:__ No | ||
| __Description:__ A list of issues addressed by the change. | ||
|
|
||
| #### data.issues.type | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Legal values:__ BUG, IMPROVEMENT, FEATURE, WORK_ITEM, REQUIREMENT, OTHER | ||
|
There was a problem hiding this comment. What is the difference between BUG and WORK_ITEM? Or FEATURE and WORK_ITEM? They all look like work items to me There was a problem hiding this comment. BUG or FEATURE describe the product and are long lived artifacts. WORK_ITEM is something you put in your backlog, describing work to be done (which could be "Fix that bug over there!"). Some people like linking one, some like linking the other, and some like linking both. There was a problem hiding this comment. But how come something that have to be done have anything to do with the model that describes events that already happened? Aren't we mixing things? There was a problem hiding this comment. I disagree. The event says that something happened: sources were changed. Why did this happen? Because of a work item, saying this had to be done. At the time you look at the event the work item may be open or closed or anything in between, but that's besides the point. You still want to be able to trace changes you made (and thereby product deltas) to work items. |
||
| __Description:__ The type of issue. | ||
|
|
||
| #### data.issues.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.issues.uri__. __data.issues.tracker__ together with __data.issues.id__ is still useful for analysis and traceability, however, as long as it can be correctly interpreted. | ||
|
|
||
| #### data.issues.id | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Description:__ The identity of the issue. This is tracker dependent - most trackers have their own issue naming schemes. | ||
|
|
||
| #### data.issues.uri | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Description:__ The URI of the issue. | ||
|
|
||
| #### data.issues.transition | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Legal values:__ RESOLVED, PARTIAL, REMOVED | ||
| __Description:__ The new state of the issue: does the change resolve it, partially resolve it or remove it? | ||
|
|
||
| ### data.gitIdentifier | ||
| __Type:__ Object | ||
| __Required:__ No | ||
| __Description:__ Identifier of a Git change. | ||
|
|
||
| #### data.gitIdentifier.commitId | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Description:__ The commit identity (hash) of the change. | ||
|
|
||
| #### data.gitIdentifier.branch | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ The name of the branch where the change was made. | ||
|
|
||
| #### data.gitIdentifier.repoName | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ The name of the repository containing the change. | ||
|
|
||
| #### data.gitIdentifier.repoUri | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Description:__ The URI of the repository containing the change. | ||
|
|
||
| ### data.svnIdentifier | ||
| __Type:__ Object | ||
| __Required:__ No | ||
| __Description:__ Identifier of a Subversion change. | ||
|
|
||
| #### data.svnIdentifier.revision | ||
| __Type:__ Integer | ||
| __Required:__ Yes | ||
| __Description:__ The revision of the change. | ||
|
|
||
| #### data.svnIdentifier.directory | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Description:__ The directory (branch/tag) of the change. | ||
|
|
||
| #### data.svnIdentifier.repoName | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ The name of the repository containing the change. | ||
|
|
||
| #### data.svnIdentifier.repoUri | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Description:__ The URI of the repository containing the change. | ||
|
|
||
| ### data.ccCompositeIdentifier | ||
|
There was a problem hiding this comment. I guess this covers base ClearCase, right? Shall we have something for UCM? Or is it possible to describe UCM coordinates using fields below? There was a problem hiding this comment. I'm not familiar enough with UCM to answer that. This syntax is based on historical usage - whether that usage is UCM or base ClearClase I don't know. |
||
| __Type:__ Object | ||
| __Required:__ No | ||
| __Description:__ Identifier of a composite ClearCase change – in other words, not single file commit, but analogous of repository-wide commits of e.g. SVN or Git. | ||
|
|
||
| #### data.ccCompositeIdentifier.vobs | ||
| __Type:__ String[] | ||
| __Required:__ Yes | ||
| __Description:__ The names of the changed ClearCase VOBs. | ||
|
|
||
| #### data.ccCompositeIdentifier.branch | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Description:__ The branch of the change. | ||
|
|
||
| #### data.ccCompositeIdentifier.configSpec | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Description:__ The URI of the relevant ClearCase config spec. | ||
|
|
||
| ### data.hgIdentifier | ||
| __Type:__ Object | ||
| __Required:__ No | ||
| __Description:__ Identifier of a Mercurial change. | ||
|
|
||
| #### data.hgIdentifier.commitId | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Description:__ The commit identity (hash) of the change. | ||
|
|
||
| #### data.hgIdentifier.branch | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ The branch of the change. | ||
|
|
||
| #### data.hgIdentifier.repoName | ||
| __Type:__ String | ||
| __Required:__ No | ||
| __Description:__ The name of the repo. | ||
|
|
||
| #### data.hgIdentifier.repoUri | ||
| __Type:__ String | ||
| __Required:__ Yes | ||
| __Description:__ The URI of the repo. | ||
|
|
||
| ## Examples | ||
| * [Simple example](https://github.com/Ericsson/eiffel-examples/blob/master/events/EiffelSourceChangeCreatedEvent/simple.json) | ||
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.
I would suggest removing id and group - there is no good generic way of identifying those automatically. I believe that we should strive to have the data model that allows automated created of the events and use it as a guiding principal. I mean, every time we want to add something we should think about the end users - how hard it will be to implement automated gathering of such info. What do you think?
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 think it's fine to include non-mandatory fields which may or may not be relevant in each particular case, the principle being "You're free to decide what to say, but if you want to say it, here's how".