Skip to content

Added all events slated for Drop 1 and updated README with links. #3

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

Added all events slated for Drop 1 and updated README with links. #3

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
5106884
Added all events slated for Drop 1.
d-stahl-ericsson May 2, 2016
17b85f0
Added links from README.md to newly added event descriptions.
d-stahl-ericsson May 2, 2016
0a6c7f8
Added INCONCLUSIVE to ConfidenceLevelModified
d-stahl-ericsson May 4, 2016
aac7396
Fixed typo.
d-stahl-ericsson May 4, 2016
6e8b8c0
Typos and clarifications.
d-stahl-ericsson May 8, 2016
05e8dd6
Improved EiffelActivityFinishedEvent description
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
34 changes: 34 additions & 0 deletions eiffel-vocabulary/EiffelActivityFinishedEvent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# EiffelActivityFinishedEvent
The EiffelActivityFinishedEvent declares that a previously queued activity (declared by [EiffelActivityQueuedEvent](./EiffelActivityQueuedEvent.md)) has finished.
Copy link
Contributor

Choose a reason for hiding this comment

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

This indicates that one could skip the started event which is not wanted behavior since we have the dequeued event for that case. Suggest to remove "previously queued" or change to "previously started".


## Data Members
### data.outcome
__Type:__ Object
__Required:__ Yes
__Description:__ The outcome of the activity.

#### data.outcome.verdict
__Type:__ String
__Required:__ Yes
__Legal values:__ SUCCESS, FAILURE, ERROR, ABORTED, TIMEOUT
Copy link

Choose a reason for hiding this comment

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

If we map those to ones that are available in Jenkins, then we could also add UNSTABLE. Which mean activity was able to run until the end, but verification check result is different from expected

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I'm really struggling with this. I don't want to tie into Jenkins just for the sake of it (see below), and I think UNSTABLE is a really poor term. I'd much rather go with actual standards rather than de facto standards (and I'd argue that this isn't even that).

But this is an area where I'm having a hard time coming up with really good terminology. Arguably we should use FAULT, ERROR and FAILURE, but the way they're defined (see e.g http://programmers.stackexchange.com/questions/184412/whats-the-difference-between-fault-error-and-defect) I don't think helps in this case.

Regardless what we propose, we should add crystal clear explanations of each value in the description.

__Description:__ A terse standardized verdict of the activity, designed to be machine readable.

#### data.outcome.description
__Type:__ String
__Required:__ No
__Description:__ A verbose description of the activity outcome, designed to provide human readers with further information.

### data.persistentLogs
__Type:__ Object[]
__Required:__ No
Copy link

@danielyinanc danielyinanc 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.

We have an inconsistency here on required... top object no, child object yes. Maybe intentional?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Intentional. The intent is: the object is optional, but if it's present, then the child may or may not be required. So it's a conditional Required if, you will.

I thought about it when typing it, realizing it might not be quite obvious :) Any suggestions?

Copy link

Choose a reason for hiding this comment

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

As I pointed on schemas... JsonSchema's ability to process this I am validating right now... logic is clear and not-insensible as I pointed in my comments over there... it is just a matter of confirming if we can implement this in some meaningful way.

__Description:__ An array of persistent log files generated during execution.

#### data.persistentLogs.name
__Type:__ String
__Required:__ Yes
__Description:__ The name of the log file.

#### data.persistentLogs.uri
__Type:__ String
__Required:__ Yes
__Description:__ The URI at which the log can be retrieved.
23 changes: 23 additions & 0 deletions eiffel-vocabulary/EiffelActivityStartedEvent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# EiffelActivityStartedEvent
The EiffelActivityStartedEvent declares that a previously queued activity (declared by [EiffelActivityQueuedEvent](./EiffelActivityQueuedEvent.md)) has started.

## Data Members
### data.executionUri
__Type:__ String
__Required:__ No
__Description:__ Any URI at which further information about the execution may be found; a typical use case is to link a CI server job execution page.

### data.liveLogs
__Type:__ Object[]
__Required:__ No
__Description:__ An array of live log files available during execution. These shall not be presumed to be stored persistently; in other words, once the activity has finished there is no guarantee that these links are valid. Persistently stored logs shall be (re-)declared by [EiffelActivityFinishedEvent](./EiffelActivityFinishedEvent.md).

#### data.liveLogs.name
__Type:__ String
__Required:__ Yes
__Description:__ The name of the log file.

#### data.liveLogs.uri
__Type:__ String
__Required:__ Yes
__Description:__ The URI at which the log can be retrieved.
44 changes: 44 additions & 0 deletions eiffel-vocabulary/EiffelArtifactCreatedEvent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# EiffelArtifactCreatedEvent
The EiffelArtifactCreatedEvent declares that a software artifact has been created, what its coordinates are, what it contains and how it was created.

## Data Members
### data.gav
__Type:__ Object
__Required:__ Yes
__Description:__ The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) of the created artifact.

#### data.gav.groupId
__Type:__ String
__Required:__ Yes
__Description:__ The groupId of the created artifact.

#### data.gav.artifactId
__Type:__ String
__Required:__ Yes
__Description:__ The artifactId of the created artifact.

#### data.gav.version
__Type:__ String
__Required:__ Yes
__Description:__ The version of the created artifact.

### data.fileInformation
__Type:__ Object[]
__Required:__ No
__Description:__ A list of the artifact file contents, following the standard established by [Apache Maven](https://maven.apache.org/pom.html).

#### data.fileInformation.classifier
__Type:__ String
__Required:__ Yes
__Description:__ The classifier of the file within the artifact. If none, an empty string shall be used.

#### data.fileInformation.extension
__Type:__ String
__Required:__ Yes
__Description:__ The extension of the file within the artifact. If none, an empty string shall be used.

### data.buildCommand
__Type:__ String
__Required:__ No
__Description:__ The command used to build the artifact within the identified environment. Used for reproducability purposes.

19 changes: 19 additions & 0 deletions eiffel-vocabulary/EiffelArtifactPublishedEvent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# EiffelArtifactPublishedEvent
The EiffelArtifactPublishedEvent declares that a software artifact (declared by [EiffelArtifactCreatedEvent](./EiffelArtifactCreatedEvent.md)) has been published and is consequently available for retrieval at one or more locations.

## Data Members
### data.locations
__Type:__ Object[]
__Required:__ Yes
__Description:__ A list of locations at which the artifact may be retrieved.

#### data.locations.type
__Type:__ String
__Required:__ Yes
__Legal values:__ ARTIFACTORY, NEXUS, PLAIN, OTHER
__Description:__ The type of location. May be used by (automated) readers to understand the method of retrieval, particularly with regards to authentication.

#### data.locations.uri
__Type:__ String
__Required:__ Yes
__Description:__ The URI at which the artifact can be retrieved.
41 changes: 41 additions & 0 deletions eiffel-vocabulary/EiffelConfidenceLevelModifiedEvent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# EiffelConfidenceLevelModifiedEvent
The EiffelConfidenceLevelModifiedEvent declares that an entity has achieved (or failed to achieve) a certain level of confidence, or in a broader sense to tag it. This is particularly useful for promoting various engineering artifacts, such as product revisions, through the continuous integration and delivery pipelin.
Copy link
Member

@fdegir fdegir May 5, 2016 •
edited
Loading

Choose a reason for hiding this comment

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

The last part of the first sentence "or in a broader sense to tag it" could be improved.

Also a typo at the end of the paragraph: pipelin -> pipeline


Confidence levels may operate at high or low levels of abstraction - ranging from "smokeTestsOk" to "releasable" or "released" - and they may group other confidence levels of lower abstraction levels. They may also be general or very niched, e.g. "releasable" or "reseabableToCustomerX". Confidence levels frequently figure in automated delivery interfaces within a tiered system context: lower level tiers issue an agreed confidence level signaling that a new version is ready for integration in a higher level tier.

## Data Members
### data.name
__Type:__ String
__Required:__ Yes
__Description:__ The name of the confidence level. It is recommended for confidence level names to conform with camelCase formatting, in line with the format of key names of the Eiffel protocol as a whole.

### data.value
__Type:__ String
__Required:__ Yes
__Legal values:__ SUCCESS, FAILURE
Copy link

Choose a reason for hiding this comment

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

Why don't we have UNSTABLE here?

Copy link

Choose a reason for hiding this comment

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

For legal values section we can use JsonSchema enum if we can define a complete list.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

We have deliberately moved away from using Jenkins enums for everything, as they are a) specific to a certain tool and b) don't make sense for all kinds of entities.
This is an example of case b). I don't think UNSTABLE makes any sense for a confidence level, and neither does things like ABORTED etc., so I went with an extremely limited set as an initial proposal. I agree that we're missing something in between, though, but that should rather be INCONCLUSIVE.

__Description:__ The value of the confidence level.

### data.issuer
__Type:__ Object
__Required:__ No
__Description:__ The individual or entity issuing the confidence level.

#### data.issuer.name
__Type:__ String
__Required:__ No
__Description:__ The name of the issuer.

#### data.issuer.email
__Type:__ String
__Required:__ No
__Description:__ The e-mail address of the issuer.

#### data.issuer.id
__Type:__ String
__Required:__ No
__Description:__ Any identity, alias or handle of the issuer, such as a corporate id or username.

#### data.issuer.group
__Type:__ String
__Required:__ No
__Description:__ Any group, such as a development team, committee or test group, to which the issuer belongs.