From aca066d940e5c33ea0aef3f13cdad3cf92a8dc6d Mon Sep 17 00:00:00 2001 From: Andrea Frittoli Date: Thu, 7 Jul 2022 15:14:09 +0100 Subject: [PATCH] Format source code events same as core Reformat the source code version control stage page to match what done for the core stage. No spec changes. Part of #13 Signed-off-by: Andrea Frittoli --- core.md | 10 +-- source-code-version-control.md | 139 +++++++++++++++++++++++++++------ 2 files changed, 121 insertions(+), 28 deletions(-) diff --git a/core.md b/core.md index 3888663c..582ceefd 100644 --- a/core.md +++ b/core.md @@ -33,7 +33,7 @@ track the build and release progress on a particular software artifact. | Field | Type | Description | Examples | |-------|------|-------------|----------| | id | `String` | Uniquely identifies the subject within the source. | `tenant1/12345-abcde`, `namespace/pipelinerun-1234` | -| source | `URI-Reference` | [source](spec.md#source) from the context | | +| source | `URI-Reference` | [source](../spec.md#source) from the context | | | pipelineName | `String` | The name of the pipeline | `MyPipeline`, `Unit tests for my repo` | | outcome | `Enum` | outcome of a finished `pipelineRun` | `success`, `error` or `failure`| | url | `URI` | url to the `pipelineRun` | `https://dashboard.org/namespace/pipelinerun-1234`, `https://api.cdsystem.com/namespace/pipelinerun-1234` | @@ -51,7 +51,7 @@ associated, in which case it is acceptable to generate only taskRun events. | Field | Type | Description | Examples | |-------|------|-------------|----------| | id | `String` | Uniquely identifies the subject within the source. | `tenant1/12345-abcde`, `namespace/taskrun-1234` | -| source | `URI-Reference` | [source](spec.md#source) from the context | | +| source | `URI-Reference` | [source](../spec.md#source) from the context | | | taskName | `String` | The name of the pipeline | `MyPipeline`, `Unit tests for my repo` | | pipelineRun | `Object` ([`pipelineRun`](#pipelinerun)) | The `pipelineRun` that this `taskRun` belongs to. | `{"id": "namespace/pipelinerun-1234"}`| | outcome | `Enum` | outcome of a finished `taskRun` | `success`, `error` or `failure`| @@ -73,7 +73,7 @@ to ignore these events if they don't apply to their use cases. | Field | Type | Description | Examples | Mandatory ✅ \| Optional ⚪ | |-------|------|-------------|----------|----------------------------| | id | `String` | Uniquely identifies the subject within the source. | `tenant1/12345-abcde`, `namespace/pipelinerun-1234` | ✅ | -| source | `URI-Reference` | [source](spec.md#source) from the context | | ⚪ | +| source | `URI-Reference` | [source](../spec.md#source) from the context | | ⚪ | | pipelineName | `String` | The name of the pipeline | `MyPipeline`, `Unit tests for my repo` | ⚪ | | url | `URI` | url to the `pipelineRun` | `https://dashboard.org/namespace/pipelinerun-1234`, `https://api.cdsystem.com/namespace/pipelinerun-1234` | ⚪ | @@ -88,7 +88,7 @@ A pipelineRun has started and it is running. | Field | Type | Description | Examples | Mandatory ✅ \| Optional ⚪ | |-------|------|-------------|----------|----------------------------| | id | `String` | Uniquely identifies the subject within the source. | `tenant1/12345-abcde`, `namespace/pipelinerun-1234` | ✅ | -| source | `URI-Reference` | [source](spec.md#source) from the context | | ⚪ | +| source | `URI-Reference` | [source](../spec.md#source) from the context | | ⚪ | | pipelineName | `String` | The name of the pipeline | `MyPipeline`, `Unit tests for my repo` | ⚪ | | url | `URI` | url to the `pipelineRun` | `https://dashboard.org/namespace/pipelinerun-1234`, `https://api.cdsystem.com/namespace/pipelinerun-1234` | ⚪ | @@ -103,7 +103,7 @@ A pipelineRun has finished, successfully or not. | Field | Type | Description | Examples | Mandatory ✅ \| Optional ⚪ | |-------|------|-------------|----------|----------------------------| | id | `String` | Uniquely identifies the subject within the source. | `tenant1/12345-abcde`, `namespace/pipelinerun-1234` | ✅ | -| source | `URI-Reference` | [source](spec.md#source) from the context | | ⚪ | +| source | `URI-Reference` | [source](../spec.md#source) from the context | | ⚪ | | pipelineName | `String` | The name of the pipeline | `MyPipeline`, `Unit tests for my repo` | ⚪ | | url | `URI` | url to the `pipelineRun` | `https://dashboard.org/namespace/pipelinerun-1234`, `https://api.cdsystem.com/namespace/pipelinerun-1234` | ⚪ | | outcome | `Enum` | outcome of a finished `pipelineRun` | `success`, `error` or `failure`| ⚪ | diff --git a/source-code-version-control.md b/source-code-version-control.md index 9c99ba5e..33bbabf1 100644 --- a/source-code-version-control.md +++ b/source-code-version-control.md @@ -10,37 +10,130 @@ description: > __Note:__ This is a work-in-progress draft version and is being worked on by members of the Events SIG. You are very welcome to join the work and the discussions! -This phase includes events related to changes in Source Code repositories that are relevant from a Continuous Delivery perspective. +Source Code Version Control events includes the subjects and predicates related to changes in Source Code repositories that are relevant from a Continuous Delivery perspective. -## Repository Events +## Subjects -These events are related to Source Code repositories +This specification defines two subjects in this stage: `repository` and `change`. Events associated with these subjects are triggered by actions performed by software developers or bots that provide useful automation for software developers. -- __Repository Created Event__: a new Source Code Repository was created to host source code for a project -- __Repository Modified Event__: a Source Code Repository modified some of its attributes, like location, or owner -- __Repository Deleted Event__: a Source Code Repository was deleted and it is not longer available -- __Branch Created Event__: a Branch inside the Repository was created -- __Branch Deleted Event__: a Branch inside the Repository was deleted +| Subject | Description | Predicates | +|---------|-------------|------------| +| [`repository`](#repository) | A software configuration management (SCM)repository | [`created`](#repository-created), [`modified`](#repository-modified), [`deleted`](#repository-deleted)| +| [`change`](#change) | A change proposed to the content of a *repository* | [`created`](#change-created), [`reviewed`](#change-reviewed), [`merged`](#change-merged), [`abandoned`](#change-abandoned), [`updated`](#change-updated)| -Repository Events MUST include the following attributes: +Each `repository` can emit events related with proposed source code `changes`. Each `change` can include a single or multiple commits that can also be tracked. -- __Event Type__: the type is restricted to include `dev.cdevents.__` prefix. For example `dev.cdevents.repository.created` or `dev.cdevents.repository.changeapproved` -- __Repository URL__: indicates the location of the source code repository for API operations, this URL needs to include the protocol used to connect to the repository. For example `git://` , `ssh://`, `https://` -- __Repository Name__: friendly name to list this repository to users +### `repository` -Optional attributes: +An SCM `repository` is identified by a `name`, an `owner` which can be a user or an organization, a `url` which is where the `repository` is hosted and optionally a `viewUrl`, which is a web location for humans to browse the content of the `repository`. -- __Repository Owner__: indicates who is the owner of the repository, usually a `user` or an `organization` -- __Repository View URL__: URL to access the repository from a user web browser +| Field | Type | Description | Examples | +|-------|------|-------------|----------| +| id | `String` | Uniquely identifies the subject within the source. | `an-org/a-repo`, `an-user/a-repo` | +| source | `URI-Reference` | [source](../spec.md#source) from the context | `my-git.example`| +| name | `String` | The name of the `repository` | `spec`, `community`, `a-repo` | +| owner | `String` | The owner of the `repository` | `cdevents`, `an-org`, `an-user`| +| url | `URI` | URL to the `repository` for API operations. This URL needs to include the protocol used to connect to the repository. | `git://my-git.example/an-org/a-repo` | +| viewUrl | `URI` | URL for humans to view the content of the `repository` | `https://my-git.example/an-org/a-repo/view`| -From each repository you can emit events related with proposed source code changes. Each change can include a single or multiple commits that can also be tracked. +### `change` -- __Change Created Event__: a source code change was created and submitted to a repository specific branch. Examples: PullRequest sent to Github, MergeRequest sent to Gitlab, Change created in Gerrit -- __Change Reviewed Event__: someone (user) or an automated system submitted an review to the source code change. A user or an automated system needs to be in charge of understanding how many approvals/rejections are needed for this change to be merged or rejected. The review event needs to include if the change is approved by the reviewer, more changes are needed or if the change is rejected. -- __Change Merged Event__: the change is merged to the target branch where it was submitted. -- __Change Abandoned Event__: a tool or a user decides that the change has been inactive for a while and it can be considered abandoned. -- __Change Updated__: the Change has been updated, for example a new commit is added or removed from an existing Change +A `change` identifies a proposed set of changes to the content of a `repository`. The usual lifecycle of a `change` The data model for `changes` is not defined yet. -Optional attributes for __Change__ Events: +| Field | Type | Description | Examples | +|-------|------|-------------|----------| +| id | `String` | Uniquely identifies the subject within the source. | `1234`, `featureBranch123` | +| source | `URI-Reference` | [source](../spec.md#source) from the context | `my-git.example`| -- (TBD) +## Events + +### `repository created` + +A new Source Code Repository was created to host source code for a project. + +- Event Type: __`dev.cdevents.repository.created`__ +- Predicate: created +- Subject: [`repository`](#repository) + +| Field | Type | Description | Examples | Mandatory ✅ \| Optional ⚪ | +|-------|------|-------------|----------|----------------------------| +| id | `String` | Uniquely identifies the subject within the source. | `an-org/a-repo`, `an-user/a-repo`, `repo123` | ✅ | +| source | `URI-Reference` | [source](../spec.md#source) from the context | `my-git.example`| ⚪ | +| name | `String` | The name of the `repository` | `spec`, `community`, `a-repo` | ✅ | +| owner | `String` | The owner of the `repository` | `cdevents`, `an-org`, `an-user`| ⚪ | +| url | `URI` | URL to the `repository` | `git://my-git.example/an-org/a-repo` | ✅ | +| viewUrl | `URI` | URL for humans to view the content of the `repository` | `https://my-git.example/an-org/a-repo/view`| ⚪ | + +### `repository modified` + +A Source Code Repository modified some of its attributes, like location, or owner. + +- Event Type: __`dev.cdevents.repository.created`__ +- Predicate: modified +- Subject: [`repository`](#repository) + +| Field | Type | Description | Examples | Mandatory ✅ \| Optional ⚪ | +|-------|------|-------------|----------|----------------------------| +| id | `String` | Uniquely identifies the subject within the source. | `an-org/a-repo`, `an-user/a-repo`, `repo123` | ✅ | +| source | `URI-Reference` | [source](../spec.md#source) from the context | `my-git.example`| ⚪ | +| name | `String` | The name of the `repository` | `spec`, `community`, `a-repo` | ✅ | +| owner | `String` | The owner of the `repository` | `cdevents`, `an-org`, `an-user`| ⚪ | +| url | `URI` | URL to the `repository` | `git://my-git.example/an-org/a-repo` | ✅ | +| viewUrl | `URI` | URL for humans to view the content of the `repository` | `https://my-git.example/an-org/a-repo/view`| ⚪ | + +### `repository deleted` + +- Event Type: __`dev.cdevents.repository.created`__ +- Predicate: modified +- Subject: [`repository`](#repository) + +| Field | Type | Description | Examples | Mandatory ✅ \| Optional ⚪ | +|-------|------|-------------|----------|----------------------------| +| id | `String` | Uniquely identifies the subject within the source. | `an-org/a-repo`, `an-user/a-repo`, `repo123` | ✅ | +| source | `URI-Reference` | [source](../spec.md#source) from the context | `my-git.example`| ⚪ | +| name | `String` | The name of the `repository` | `spec`, `community`, `a-repo` | ⚪ | +| owner | `String` | The owner of the `repository` | `cdevents`, `an-org`, `an-user`| ⚪ | +| url | `URI` | URL to the `repository` | `git://my-git.example/an-org/a-repo` | ⚪ | +| viewUrl | `URI` | URL for humans to view the content of the `repository` | `https://my-git.example/an-org/a-repo/view`| ⚪ | + +### `repository branch created` + +A branch inside the Repository was created. + +🚧 The branch model is work in progress. + +### `repository branch deleted` + +A branch inside the Repository was deleted. + +🚧 The branch model is work in progress. + +### `change created` + +A source code change was created and submitted to a repository specific branch. Examples: PullRequest sent to Github, MergeRequest sent to Gitlab, Change created in Gerrit. + +🚧 The change model is work in progress. + +### `change reviewed` + +Someone (user) or an automated system submitted an review to the source code change. A user or an automated system needs to be in charge of understanding how many approvals/rejections are needed for this change to be merged or rejected. The review event needs to include if the change is approved by the reviewer, more changes are needed or if the change is rejected. + +🚧 The change model is work in progress. + +### `change merged` + +A change is merged to the target branch where it was submitted. + +🚧 The change model is work in progress. + +### `change abandoned` + +A tool or a user decides that the change has been inactive for a while and it can be considered abandoned. + +🚧 The change model is work in progress. + +### `change updated` + +A Change has been updated, for example a new commit is added or removed from an existing Change. + +🚧 The change model is work in progress.