#1275 Review of properties

doc/dev-guide/README.md

@@ -2,5 +2,9 @@
 
 > WORK IN PROGRESS. JUST GETTING STARTED.
 
-* [Backend](backend/README.md)
-* [UI](ui/README.md)
+* General
+  * [Backend](backend/README.md)
+  * [UI](ui/README.md)
+* Components
+  * [Model](components/core/README.md) - core model of Ontrack
+  * [Properties](components/properties/README.md)

doc/dev-guide/components/core/README.md

@@ -0,0 +1,9 @@
+# Core model of Ontrack
+
+At the core of the model of Ontrack lie the _project entities_.
+
+This is a set of classes starting at _project_ level:
+
+![Ontrack core model](model.png)
+
+* project - this is the top-level object in Ontrack.

doc/dev-guide/components/core/model.puml

@@ -0,0 +1,30 @@
+@startuml
+object Project
+object Branch
+object Build
+object "Promotion level" as PromotionLevel
+object "Validation stamp" as ValidationStamp
+object "Promotion run" as PromotionRun
+object "Validation run" as ValidationRun
+object "Validation run status" as ValidationRunStatus
+object "Run info" as RunInfo
+
+Project o-- "*" Branch
+
+Branch o-- "*" Build
+Branch o-- "*" PromotionLevel
+Branch o-- "*" ValidationStamp
+
+Build o-- "*" PromotionRun
+PromotionRun --> "1" PromotionLevel
+
+Build --> "*" Build
+
+Build o-- "*" ValidationRun
+ValidationRun --> "1" ValidationStamp
+ValidationRun o-- "*" ValidationRunStatus
+
+Build o-- "1" RunInfo
+ValidationRun o-- "1" RunInfo
+
+@enduml

doc/dev-guide/components/extensions/README.md

@@ -0,0 +1,3 @@
+# Extensions
+
+TBD

doc/dev-guide/components/properties/README.md

@@ -0,0 +1,68 @@
+# Properties
+
+Properties are meta-information which can be attached to [_project entities_](../core/README.md).
+
+## Developing a property
+
+Properties are code components with facets both in the backend and the frontend.
+
+### Backend
+
+Any property must be coded in as [extension](../extensions/README.md) of the `PropertyType<T>` type.
+
+Typically, implementations will extend the `AbstractPropertyType<T>` abstract class.
+
+The `<T>` parameter represents the actual type of what needs to be attached to the project entities and the `PropertyType<T>` is responsible for:
+
+* converting to/from this data to frontend API (as JSON)
+* converting to/from this data to the storage (as JSON)
+
+The ID (or type) of a property type is used in many places to identify which property is considered.
+
+It's always the FQCN of the implemented `PropertyType` and cannot be configured.
+
+#### Documentation considerations
+
+All properties are exported by default to the user documentation.
+
+The `description` of the property type is used to describe the property and the `T` property class is used to describe the fields that a client must provide to an API.
+
+#### GraphQL considerations
+
+All properties are available by default through the generic properties API (read & write).
+
+For specific GraphQL mutations, the `PropertyMutationProvider` interface must be implemented as a component.
+
+#### CasC considerations
+
+TBD
+
+### Frontend
+
+Each property, to be rendered on the frontend, must provide two components in the `components/framework/properties/<folder>` folder, where `<folder>` is the FQCN of the property type class, after the `net.nemerosa.ontrack.extension`:
+
+* `Icon.js` - exports a default function which returns the icon part of a property. It can be as simple as:
+
+```javascript
+import {FaTags} from "react-icons/fa";
+
+export default function Icon() {
+    return <FaTags/>
+}
+```
+
+* `Display.js` - exports a default function which returns the React component used to display the _value_ of the property. It takes as arguments the `property` object, which contains, in its `value` field, the JSON representation of the property type (`T`).
+
+Example:
+
+```javascript
+import {Tag} from "antd";
+
+export default function Display({property}) {
+    return (
+        <>
+            <Tag color="green">{property.value.name}</Tag>
+        </>
+    )
+}
+```

ontrack-docs/src/docs/asciidoc/appendixes.adoc

@@ -11,6 +11,8 @@ include::appendix-notifications.adoc[]
 
 include::appendix-workflow-node-executors.adoc[]
 
+include::properties/index.adoc[]
+
 // include::appendix-deprecations.adoc[]
 
 // include::appendix-roadmap.adoc[]

ontrack-docs/src/docs/asciidoc/properties/index.adoc

@@ -0,0 +1,60 @@
+[[appendix-properties-index]]
+=== List of properties
+
+* <<property-net.nemerosa.ontrack.extension.artifactory.property.ArtifactoryPromotionSyncPropertyType,Artifactory promotion sync>>
+* <<property-net.nemerosa.ontrack.extension.bitbucket.cloud.property.BitbucketCloudProjectConfigurationPropertyType,Bitbucket Cloud configuration>>
+* <<property-net.nemerosa.ontrack.extension.general.AutoPromotionLevelPropertyType,Auto promotion levels>>
+* <<property-net.nemerosa.ontrack.extension.general.AutoPromotionPropertyType,Auto promotion>>
+* <<property-net.nemerosa.ontrack.extension.general.AutoValidationStampPropertyType,Auto validation stamps>>
+* <<property-net.nemerosa.ontrack.extension.general.BuildLinkDisplayPropertyType,Build link display options>>
+* <<property-net.nemerosa.ontrack.extension.general.LinkPropertyType,Links>>
+* <<property-net.nemerosa.ontrack.extension.general.MainBuildLinksProjectPropertyType,Main build links>>
+* <<property-net.nemerosa.ontrack.extension.general.MessagePropertyType,Message>>
+* <<property-net.nemerosa.ontrack.extension.general.MetaInfoPropertyType,Meta information>>
+* <<property-net.nemerosa.ontrack.extension.general.PreviousPromotionConditionPropertyType,Previous promotion condition>>
+* <<property-net.nemerosa.ontrack.extension.general.PromotionDependenciesPropertyType,Promotion dependencies>>
+* <<property-net.nemerosa.ontrack.extension.general.ReleasePropertyType,Release>>
+* <<property-net.nemerosa.ontrack.extension.general.ReleaseValidationPropertyType,Validation on release/label>>
+* <<property-net.nemerosa.ontrack.extension.git.branching.BranchingModelPropertyType,Branching Model>>
+* <<property-net.nemerosa.ontrack.extension.git.property.GitBranchConfigurationPropertyType,Git branch>>
+* <<property-net.nemerosa.ontrack.extension.git.property.GitCommitPropertyType,Git commit>>
+* <<property-net.nemerosa.ontrack.extension.git.property.GitProjectConfigurationPropertyType,Git configuration>>
+* <<property-net.nemerosa.ontrack.extension.github.property.GitHubProjectConfigurationPropertyType,GitHub configuration>>
+* <<property-net.nemerosa.ontrack.extension.github.workflow.BuildGitHubWorkflowRunPropertyType,GitHub Workflow Run>>
+* <<property-net.nemerosa.ontrack.extension.github.workflow.ValidationRunGitHubWorkflowJobPropertyType,GitHub Workflow Job>>
+* <<property-net.nemerosa.ontrack.extension.gitlab.property.GitLabProjectConfigurationPropertyType,GitLab configuration>>
+* <<property-net.nemerosa.ontrack.extension.jenkins.JenkinsBuildPropertyType,Jenkins Build>>
+* <<property-net.nemerosa.ontrack.extension.jenkins.JenkinsJobPropertyType,Jenkins Job>>
+* <<property-net.nemerosa.ontrack.extension.jira.JIRAFollowLinksPropertyType,JIRA Links to follow>>
+* <<property-net.nemerosa.ontrack.extension.sonarqube.property.SonarQubePropertyType,SonarQube>>
+* <<property-net.nemerosa.ontrack.extension.stale.StalePropertyType,Stale branches>>
+* <<property-net.nemerosa.ontrack.extension.stash.property.StashProjectConfigurationPropertyType,Bitbucket Server configuration>>
+
+include::property-net.nemerosa.ontrack.extension.artifactory.property.ArtifactoryPromotionSyncPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.bitbucket.cloud.property.BitbucketCloudProjectConfigurationPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.general.AutoPromotionLevelPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.general.AutoPromotionPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.general.AutoValidationStampPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.general.BuildLinkDisplayPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.general.LinkPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.general.MainBuildLinksProjectPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.general.MessagePropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.general.MetaInfoPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.general.PreviousPromotionConditionPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.general.PromotionDependenciesPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.general.ReleasePropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.general.ReleaseValidationPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.git.branching.BranchingModelPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.git.property.GitBranchConfigurationPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.git.property.GitCommitPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.git.property.GitProjectConfigurationPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.github.property.GitHubProjectConfigurationPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.github.workflow.BuildGitHubWorkflowRunPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.github.workflow.ValidationRunGitHubWorkflowJobPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.gitlab.property.GitLabProjectConfigurationPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.jenkins.JenkinsBuildPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.jenkins.JenkinsJobPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.jira.JIRAFollowLinksPropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.sonarqube.property.SonarQubePropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.stale.StalePropertyType.adoc[]
+include::property-net.nemerosa.ontrack.extension.stash.property.StashProjectConfigurationPropertyType.adoc[]

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.artifactory.property.ArtifactoryPromotionSyncPropertyType.adoc

@@ -0,0 +1,21 @@
+[[property-net.nemerosa.ontrack.extension.artifactory.property.ArtifactoryPromotionSyncPropertyType]]
+==== Artifactory promotion sync
+
+ID: `net.nemerosa.ontrack.extension.artifactory.property.ArtifactoryPromotionSyncPropertyType`
+
+Synchronisation of the promotions with Artifactory build statuses
+
+Scope:
+
+* branch
+
+Configuration:
+
+* **buildName** - String - required - buildName field
+
+* **buildNameFilter** - String - required - buildNameFilter field
+
+* **configuration** - String - required - Name of the Artifactory configuration
+
+* **interval** - Int - required - interval field
+

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.bitbucket.cloud.property.BitbucketCloudProjectConfigurationPropertyType.adoc

@@ -0,0 +1,21 @@
+[[property-net.nemerosa.ontrack.extension.bitbucket.cloud.property.BitbucketCloudProjectConfigurationPropertyType]]
+==== Bitbucket Cloud configuration
+
+ID: `net.nemerosa.ontrack.extension.bitbucket.cloud.property.BitbucketCloudProjectConfigurationPropertyType`
+
+Associates the project with a Bitbucket Cloud repository
+
+Scope:
+
+* project
+
+Configuration:
+
+* **configuration** - String - required - Name of the Bitbucket Cloud configuration
+
+* **indexationInterval** - Int - required - How often to index the repository, in minutes. Use 0 to disable indexation.
+
+* **issueServiceConfigurationIdentifier** - String - optional - Identifier for the issue service
+
+* **repository** - String - required - Name of the repository
+

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.general.AutoPromotionLevelPropertyType.adoc

@@ -0,0 +1,15 @@
+[[property-net.nemerosa.ontrack.extension.general.AutoPromotionLevelPropertyType]]
+==== Auto promotion levels
+
+ID: `net.nemerosa.ontrack.extension.general.AutoPromotionLevelPropertyType`
+
+If set, this property allows promotion levels to be created automatically from predefined promotion levels
+
+Scope:
+
+* project
+
+Configuration:
+
+* **isAutoCreate** - Boolean - required - isAutoCreate field
+

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.general.AutoPromotionPropertyType.adoc

@@ -0,0 +1,21 @@
+[[property-net.nemerosa.ontrack.extension.general.AutoPromotionPropertyType]]
+==== Auto promotion
+
+ID: `net.nemerosa.ontrack.extension.general.AutoPromotionPropertyType`
+
+Allows a promotion level to be granted on a build as soon as a list of validation stamps and/or other promotions has been passed
+
+Scope:
+
+* promotion level
+
+Configuration:
+
+* **exclude** - String - required - Regular expression to exclude validation stamps by name
+
+* **include** - String - required - Regular expression to include validation stamps by name
+
+* **promotionLevels** - List - required - List of needed promotion levels
+
+* **validationStamps** - List - required - List of needed validation stamps
+

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.general.AutoValidationStampPropertyType.adoc

@@ -0,0 +1,17 @@
+[[property-net.nemerosa.ontrack.extension.general.AutoValidationStampPropertyType]]
+==== Auto validation stamps
+
+ID: `net.nemerosa.ontrack.extension.general.AutoValidationStampPropertyType`
+
+If set, this property allows validation stamps to be created automatically from predefined validation stamps
+
+Scope:
+
+* project
+
+Configuration:
+
+* **autoCreate** - Boolean - required - If true, creates validations from predefined ones
+
+* **autoCreateIfNotPredefined** - Boolean - required - If true, creates validations even if not predefined
+

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.general.BuildLinkDisplayPropertyType.adoc

@@ -0,0 +1,15 @@
+[[property-net.nemerosa.ontrack.extension.general.BuildLinkDisplayPropertyType]]
+==== Build link display options
+
+ID: `net.nemerosa.ontrack.extension.general.BuildLinkDisplayPropertyType`
+
+Configuration of display options for the build links towards this project.
+
+Scope:
+
+* project
+
+Configuration:
+
+* **useLabel** - Boolean - required - useLabel field
+

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.general.LinkPropertyType.adoc

@@ -0,0 +1,21 @@
+[[property-net.nemerosa.ontrack.extension.general.LinkPropertyType]]
+==== Links
+
+ID: `net.nemerosa.ontrack.extension.general.LinkPropertyType`
+
+List of links.
+
+Scope:
+
+* project
+* branch
+* promotion level
+* validation stamp
+* build
+* promotion run
+* validation run
+
+Configuration:
+
+* **links** - List - required - links field
+

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.general.MainBuildLinksProjectPropertyType.adoc

@@ -0,0 +1,18 @@
+[[property-net.nemerosa.ontrack.extension.general.MainBuildLinksProjectPropertyType]]
+==== Main build links
+
+ID: `net.nemerosa.ontrack.extension.general.MainBuildLinksProjectPropertyType`
+
+List of project labels which describes the list of build links
+to display in a build links decoration.
+
+Scope:
+
+* project
+
+Configuration:
+
+* **labels** - List - required - labels field
+
+* **overrideGlobal** - Boolean - required - overrideGlobal field
+

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.general.MessagePropertyType.adoc

@@ -0,0 +1,23 @@
+[[property-net.nemerosa.ontrack.extension.general.MessagePropertyType]]
+==== Message
+
+ID: `net.nemerosa.ontrack.extension.general.MessagePropertyType`
+
+Associates an arbitrary message (and its type) to an entity. Will be displayed as a decorator in the UI.
+
+Scope:
+
+* project
+* branch
+* promotion level
+* validation stamp
+* build
+* promotion run
+* validation run
+
+Configuration:
+
+* **text** - String - required - Content of the message
+
+* **type** - ERROR, WARNING, INFO - required - Type of message
+

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.general.MetaInfoPropertyType.adoc

@@ -0,0 +1,21 @@
+[[property-net.nemerosa.ontrack.extension.general.MetaInfoPropertyType]]
+==== Meta information
+
+ID: `net.nemerosa.ontrack.extension.general.MetaInfoPropertyType`
+
+List of meta information properties
+
+Scope:
+
+* project
+* branch
+* promotion level
+* validation stamp
+* build
+* promotion run
+* validation run
+
+Configuration:
+
+* **items** - List - required - items field
+