Skip to content

Latest commit

 

History

History
329 lines (268 loc) · 14.5 KB

EiffelSourceChangeCreatedEvent.md

File metadata and controls

329 lines (268 loc) · 14.5 KB

EiffelSourceChangeCreatedEvent (SCC)

The EiffelSourceChangeCreatedEvent declares that a change to sources has been made, but not yet submitted (see EiffelSourceChangeSubmittedEvent). 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.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

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.

Links

BASE

Required: No
Legal targets: EiffelSourceChangeSubmittedEvent
Multiple allowed: No
Description: Identifies the base revision of the created source change.

PREVIOUS_VERSION

Required: No
Legal targets: EiffelSourceChangeCreatedEvent
Multiple allowed: Yes
Description: Identifies a latest previous version (there may be more than one in case of merges) of the created source change.

PARTIALLY_RESOLVED_ISSUE

Required: No
Legal targets: EiffelIssueDefinedEvent
Multiple allowed: Yes
Description: Identifies an issue that this event partially resolves. That is, this SCC introduces some change that has advanced an issue towards a resolved state, but not completely resolved.

RESOLVED_ISSUE

Required: No
Legal targets: EiffelIssueDefinedEvent
Multiple allowed: Yes
Description: Identifies an issue that this SCC is claiming it has done enough to resolve. This is not an authoritative resolution, only a claim. The issue may or may not change status as a consequence this, e.g. through a successful verification or a manual update on the issue tracker.

DERESOLVED_ISSUE

Required: No
Legal targets: EiffelIssueDefinedEvent
Multiple allowed: Yes
Description: Identifies an issue which was previously resolved, but that this SCC claims it has made changes to warrant removing the resolved status. For example, if an issue "Feature X" was resolved, but this SCC removed the implmentation that led to "Feature X" being resolved, that issue should no longer be considered resolved.

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, EiffelTestSuiteStartedEvent
Multiple allowed: No
Description: Identifies the activity or test suite of which this event constitutes a part.

FLOW_CONTEXT

Required: No
Legal targets: EiffelFlowContextDefinedEvent
Multiple allowed: Yes
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
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
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 for more information.

meta.time

Type: Integer
Format: UNIX Epoch time, in milliseconds.
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: String
Format: purl specification
Required: No
Description: The identity of the serializer software used to construct the event, in purl format.

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 for further information.

meta.security.sdm

Type: Object
Format:
Required: No
Description: An optional object for properties supporting the Strong Distribution Model. 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
3.0.0 Current version Introduced purl identifiers instead of GAVs (see Issue 182)
2.0.0 0706840 Replaced data.issues with links
1.1.0 edition-toulouse Multiple links of type FLOW_CONTEXT allowed.
1.0.0 edition-bordeaux Initial version.

Examples