Skip to content

Completed description of links object #2

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.

Sign up for GitHub

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
merged 6 commits into from
May 10, 2016
Merged

Completed description of links object #2

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4def66d
Completed description of links object
d-stahl-ericsson May 2, 2016
45dc4c7
Fixed copy-paste mishap.
d-stahl-ericsson May 4, 2016
9c2e4f2
Changed links.previous to links.previousVersions.
d-stahl-ericsson May 4, 2016
c4883f3
Clarified relationship between links.activityExecution and links.context
d-stahl-ericsson May 4, 2016
adf395e
Split links.previousActivityExectuion from links.previousVersions
d-stahl-ericsson May 10, 2016
3a6f475
Removed incorrect link targets.
d-stahl-ericsson May 10, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 131 additions & 2 deletions eiffel-syntax-and-usage/the-links-object.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ __Description:__ Identifies one or more causes of the event occurring. SHOULD no
__Type:__ String
__Required in:__ None
__Optional in:__ Any
__Legal targets:__ [EiffelActivityQueuedEvent](../eiffel-vocabulary/EiffelActivityQueuedEvent.md), [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md)
__Legal targets:__ [EiffelActivityQueuedEvent](../eiffel-vocabulary/EiffelActivityQueuedEvent.md),
[EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md)
__Description:__ Identifies a the activity or test suite of which the event constitutes a part. SHOULD not be used in conjunction with __links.causes__, see above. Note that multiple layers may be modeled using __links.context__, e.g. an activity being part of another activity.

### links.flowContext
Expand All @@ -25,5 +26,133 @@ __Optional in:__ Any
__Legal targets:__ [EiffelFlowContextDefinedEvent](../eiffel-vocabulary/EiffelFlowContextDefinedEvent.md)
__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.

### links.activityExecution
__Type:__ String
__Required in:__ [EiffelActivityDequeuedEvent](../eiffel-vocabulary/EiffelActivityDequeuedEvent),
[EiffelActivityStartedEvent](../eiffel-vocabulary/EiffelActivityStartedEvent),
[EiffelActivityFinishedEvent](../eiffel-vocabulary/EiffelActivityFinishedEvent)
__Optional in:__ None
__Legal targets:__ [EiffelActivityQueuedEvent](../eiffel-vocabulary/EiffelActivityQueuedEvent.md)
__Description:__ Declares the activity execution the event relates to. In other words, [EiffelActivityQueuedEvent](../eiffel-vocabulary/EiffelActivityQueuedEvent.md) acts as a handle for the activity execution.
Copy link

@rogpers-ericsson rogpers-ericsson May 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The relation between links.activityExecution and links.context needs to be clarified.

Copy link
Contributor Author

@d-stahl-ericsson d-stahl-ericsson May 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pushed a stab as explaining this difference. That being said, it's not a given that these should be separate link types. It would be entirely possible to merge context, activityExecution, testCaseExecution and/or testSuiteExecution - in each case, the meaning could be implicitly derived from the target. I'm not really a fan of that, however, I'd like explicit semantics wherever possible.


### links.previous
Copy link
Contributor

@p-backman-ericsson p-backman-ericsson May 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Previous is an anomaly in the links section. We generally use plural form of a noun for link arrays and previous is an adjective (does not have a plural form). Should we use previousVersions instead to be consistent?

Copy link
Contributor Author

@d-stahl-ericsson d-stahl-ericsson May 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right. I didn't think about that. I pushed a new commit changing to previousVersions.

__Type:__ String[]
__Required in:__ None
__Optional in:__ [EiffelActivityStartedEvent](../eiffel-vocabulary/EiffelActivityStartedEvent.md),
[EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md),
[EiffelDocumentationCreatedEvent](../eiffel-vocabulary/EiffelDocumentationCreatedEvent.md),
[EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md),
[EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md),
[EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md),
[EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md)
__Legal targets:__ [EiffelActivityStartedEvent](../eiffel-vocabulary/EiffelActivityStartedEvent.md),
[EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md),
[EiffelDocumentationCreatedEvent](../eiffel-vocabulary/EiffelDocumentationCreatedEvent.md),
[EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md),
[EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md),
[EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md),
[EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md)
__Description:__ Identifies the latest previous version(s) of the engineering artifact the event represents, e.g. the previous version of the artifact, the previous version of the composition etc. The target event type SHALL be the same as the source event type. In most cases a single element array is to be expected: multiple elements are intended for representing merges.

### links.composition
__Type:__ String
__Required in:__ None
__Optional in:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md)
Copy link

@rogpers-ericsson rogpers-ericsson May 4, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This opens up for the possibility of having "undefined" artifacts, i.e. artifacts we do not know the contents of.

Or maybe "Optional in" should be expressed in using some other wording, e.g. "Expected in" or something like it.

Copy link
Contributor Author

@d-stahl-ericsson d-stahl-ericsson May 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. I think that's perfectly acceptable? If you don't want to/can't define it, then you shouldn't have to. But when you do, it should be unambiguously clear how it's done.

This goes back to a more general principle: I don't think it's a major problem to be rather generous with optional fields: missing information is a lot easier to deal with than ambiguous information.

Copy link

@rogpers-ericsson rogpers-ericsson May 4, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have no problem with the general principle. It's the word "optional" that I think may be an issue. To me it's a bit "too loose". Somehow the intention of linking events is "lost". It's sort of the difference between SHOULD and MAY.

__Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md)
__Description:__ Identifies the composition from which an artifact was built.

### links.environment
__Type:__ String
__Required in:__ None
__Optional in:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md),
[EiffelArtifactTestCaseStartedEvent](../eiffel-vocabulary/EiffelArtifactTestCaseStartedEvent.md)
__Legal targets:__ [EiffelEnvironmentDefinedEvent](../eiffel-vocabulary/EiffelEnvironmentDefinedEvent.md)
__Description:__ Identifies the environment in which an event occurred, e.g. in which environment an artifact was built.

### links.environment
Copy link
Contributor

@p-backman-ericsson p-backman-ericsson May 4, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be links.artifact

__Type:__ String
__Required in:__ [EiffelArtifactPublishedEvent](../eiffel-vocabulary/EiffelArtifactPublishedEvent.md)
__Optional in:__ None
__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md)
__Description:__ Identifies the artifact that was published.

### links.subjects
__Type:__ String[]
__Required in:__ [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md)
__Optional in:__ None
__Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md),
[EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md),
[EiffelDocumentationCreatedEvent](../eiffel-vocabulary/EiffelDocumentationCreatedEvent.md),
[EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md),
[EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md)
__Description:__ Identifies the subject(s) of the confidence level.

### links.elements
__Type:__ String[]
__Required in:__ None
__Optional in:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md)
__Legal targets:__ [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md),
[EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md),
[EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md),
[EiffelDocumentationCreatedEvent](../eiffel-vocabulary/EiffelDocumentationCreatedEvent.md)
__Description:__ Identifies elements and or sub-compositions of the composition. The latter is particularly useful for documenting large and potentially decentralized compositions, and may be used to reduce the need to repeat large compositions in which only small parts are subject to frequent change.

### links.base
__Type:__ String
__Required in:__ None
__Optional in:__ [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md)
__Legal targets:__ [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md)
__Description:__ Identifies the base revision of the proposed change.

### links.change
__Type:__ String
__Required in:__ None
__Optional in:__ [EiffelSourceChangeSubmittedEvent](../eiffel-vocabulary/EiffelSourceChangeSubmittedEvent.md)
__Legal targets:__ [EiffelSourceChangeCreatedEvent](../eiffel-vocabulary/EiffelSourceChangeCreatedEvent.md)
__Description:__ Identifies the change that was submitted.

### links.testSuiteExecution
__Type:__ String
__Required in:__ [EiffelTestSuiteFinishedEvent](../eiffel-vocabulary/EiffelTestSuiteFinishedEvent.md)
__Optional in:__ None
__Legal targets:__ [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md)
__Description:__ Identifies the relevant test suite execution. In other words, [EiffelTestSuiteStartedEvent](../eiffel-vocabulary/EiffelTestSuiteStartedEvent.md) acts as a handle for a particular test suite execution.

### links.testCaseExecution
__Type:__ String
__Required in:__ [EiffelTestCaseFinishedEvent](../eiffel-vocabulary/EiffelTestCaseFinishedEvent.md)
__Optional in:__ None
__Legal targets:__ [EiffelTestCaseStartedEvent](../eiffel-vocabulary/EiffelTestCaseStartedEvent.md)
__Description:__ Identifies the relevant test case execution. In other words, [EiffelTestCaseStartedEvent](../eiffel-vocabulary/EiffelTestCaseStartedEvent.md) acts as a handle for a particular test case execution.

### links.iut
__Type:__ String
__Required in:__ [EiffelTestCaseStartedEvent](../eiffel-vocabulary/EiffelTestCaseStartedEvent.md)
__Optional in:__ None
__Legal targets:__ [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md),
[EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md)
__Description:__ Identifies the Item Under Test.

### links.terc
__Type:__ String
__Required in:__ None
__Optional in:__ [EiffelTestCaseStartedEvent](../eiffel-vocabulary/EiffelTestCaseStartedEvent.md)
__Legal targets:__ [EiffelTestExecutionRecipeCollectionCreatedEvent](../eiffel-vocabulary/EiffelTestExecutionRecipeCollectionCreatedEvent.md)
__Description:__ Identifies the Test Execution Recipe Collection dictating the execution of the test case.

### links.modifiedAnnouncement
__Type:__ String
__Required in:__ None
__Optional in:__ [EiffelAnnouncementEvent](../eiffel-vocabulary/EiffelAnnouncementEvent.md)
__Legal targets:__ [EiffelAnnouncementEvent](../eiffel-vocabulary/EiffelAnnouncementEvent.md),
[EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md)
Copy link
Contributor

@p-backman-ericsson p-backman-ericsson May 10, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't think EiffelCompositionDefinedEvent should be a legal target here.

__Description:__ Identifies an announcement of which this event represents an update or modification, if any. Example usage is to declare the end to a previously announced situation.

### links.subConfidenceLevels
__Type:__ String
__Required in:__ None
__Optional in:__ [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md)
__Legal targets:__ [EiffelConfidenceLevelModifiedEvent](../eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md),
[EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md)
Copy link
Contributor

@p-backman-ericsson p-backman-ericsson May 10, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't think EiffelCompositionDefinedEvent should be a legal target here.

__Description:__ Used in events summarizing multiple confidence levels. Example use case: the confidence level "allTestsOk" summarizes the confidence levels "unitTestsOk, "scenarioTestsOk" and "deploymentTestsOk", and consequently links to them using this field. This is intended for purely descriptive, rather than prescriptive, use.

### More links to be added...
3 changes: 0 additions & 3 deletions eiffel-vocabulary/EiffelActivityDequeuedEvent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,3 @@ The EiffelActivityDequeuedEvent signals that an activity previously queued for e
__Type:__ String
__Required:__ No
__Description:__ Any human readable information as to the reason for dequeueing.

## Schema
TBD
3 changes: 0 additions & 3 deletions eiffel-vocabulary/EiffelActivityQueuedEvent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,3 @@ __Type:__ String
__Required:__ No
__Legal values:__ MANUAL, SEMI_AUTOMATED, AUTOMATED, OTHER
__Description:__ The type of execution (often related to, but ultimately separate from, __data.trigger.type__).

## Schema
TBD