#1275 Review of properties

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.git.branching.BranchingModelPropertyType.adoc

@@ -11,5 +11,5 @@ Scope:
 
 Configuration:
 
-* **patterns** - List - required - patterns field
+* **patterns** - List - required - List of branch patterns (name & value). The name is the category of branch and the value is a regular expression on the SCM branch.
 

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.git.property.GitBranchConfigurationPropertyType.adoc

@@ -11,15 +11,15 @@ Scope:
 
 Configuration:
 
-* **branch** - String - required - branch field
+* **branch** - String - required - Git branch or pull request ID
 
-* **buildCommitLink** - Object - optional - buildCommitLink field
+* **buildCommitLink** - Object - optional - How builds are linked to their Git commit
 
 ** **data** - JSON - optional - Configuration of the service
 
 ** **id** - String - required - ID of the service
 
-* **buildTagInterval** - Int - required - buildTagInterval field
+* **buildTagInterval** - Int - required - Interval in minutes for build/tag synchronization
 
-* **isOverride** - Boolean - required - isOverride field
+* **isOverride** - Boolean - required - Build overriding policy when synchronizing
 

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.git.property.GitCommitPropertyType.adoc

@@ -11,5 +11,5 @@ Scope:
 
 Configuration:
 
-* **commit** - String - required - commit field
+* **commit** - String - required - Commit hash
 

ontrack-docs/src/docs/asciidoc/properties/property-net.nemerosa.ontrack.extension.github.workflow.BuildGitHubWorkflowRunPropertyType.adoc

@@ -13,3 +13,15 @@ Configuration:
 
 * **workflows** - List - required - All workflows associated to a build.
 
+** **event** - String - optional - Event having led to the creation of this build
+
+** **name** - String - required - Name of the workflow
+
+** **runId** - Long - required - ID of the run
+
+** **runNumber** - Int - required - Number of the run
+
+** **running** - Boolean - required - True if the run is still flagged as running
+
+** **url** - String - required - Link to the GitHub Workflow run
+

ontrack-extension-general/src/main/java/net/nemerosa/ontrack/extension/general/BuildLinkDisplayProperty.kt

@@ -1,5 +1,7 @@
 package net.nemerosa.ontrack.extension.general
 
+import net.nemerosa.ontrack.model.annotations.APIDescription
+
 /**
  * Configuration of the display options for build links
  * targeting a project.
@@ -12,6 +14,12 @@ package net.nemerosa.ontrack.extension.general
  * the release name if available, and then the build name as a default.
  */
 class BuildLinkDisplayProperty(
+ @APIDescription(
+ """Configuration at project label to specify that a
+ build link decoration should use the release/label
+ of a build when available. By default, it displays
+ the release name if available, and then the build name as a default."""
+ )
  val useLabel: Boolean
 )
 

ontrack-extension-git/src/main/java/net/nemerosa/ontrack/extension/git/branching/BranchingModelProperty.kt

@@ -1,7 +1,9 @@
 package net.nemerosa.ontrack.extension.git.branching
 
+import net.nemerosa.ontrack.model.annotations.APIDescription
 import net.nemerosa.ontrack.model.support.NameValue
 
 class BranchingModelProperty(
- val patterns: List<NameValue>
+ @APIDescription("List of branch patterns (name & value). The name is the category of branch and the value is a regular expression on the SCM branch.")
+ val patterns: List<NameValue>
 )

ontrack-extension-git/src/main/java/net/nemerosa/ontrack/extension/git/property/GitBranchConfigurationProperty.kt

@@ -1,29 +1,34 @@
 package net.nemerosa.ontrack.extension.git.property
 
+import net.nemerosa.ontrack.model.annotations.APIDescription
 import net.nemerosa.ontrack.model.docs.DocumentationField
 import net.nemerosa.ontrack.model.structure.ServiceConfiguration
 
 class GitBranchConfigurationProperty(
 
- /**
- * Git branch or pull request ID
- */
- val branch: String,
+ /**
+ * Git branch or pull request ID
+ */
+ @APIDescription("Git branch or pull request ID")
+ val branch: String,
 
- /**
- * Build link
- */
- @DocumentationField
- val buildCommitLink: ServiceConfiguration?,
+ /**
+ * Build link
+ */
+ @DocumentationField
+ @APIDescription("How builds are linked to their Git commit")
+ val buildCommitLink: ServiceConfiguration?,
 
- /**
- * Build overriding policy when synchronizing
- */
- val isOverride: Boolean,
+ /**
+ * Build overriding policy when synchronizing
+ */
+ @APIDescription("Build overriding policy when synchronizing")
+ val isOverride: Boolean,
 
- /**
- * Interval in minutes for build/tag synchronization
- */
- val buildTagInterval: Int
+ /**
+ * Interval in minutes for build/tag synchronization
+ */
+ @APIDescription("Interval in minutes for build/tag synchronization")
+ val buildTagInterval: Int
 
 )

ontrack-extension-git/src/main/java/net/nemerosa/ontrack/extension/git/property/GitCommitProperty.kt

@@ -1,5 +1,8 @@
 package net.nemerosa.ontrack.extension.git.property
 
+import net.nemerosa.ontrack.model.annotations.APIDescription
+
 class GitCommitProperty(
+ @APIDescription("Commit hash")
  val commit: String
 )

ontrack-extension-github/src/main/java/net/nemerosa/ontrack/extension/github/workflow/BuildGitHubWorkflowRunProperty.kt

@@ -1,6 +1,7 @@
 package net.nemerosa.ontrack.extension.github.workflow
 
 import net.nemerosa.ontrack.model.annotations.APIDescription
+import net.nemerosa.ontrack.model.docs.DocumentationList
 
 /**
  * Links between GitHub Workflow runs and an Ontrack build.
@@ -9,6 +10,7 @@ import net.nemerosa.ontrack.model.annotations.APIDescription
  */
 data class BuildGitHubWorkflowRunProperty(
  @APIDescription("All workflows associated to a build.")
+ @DocumentationList
  val workflows: List<BuildGitHubWorkflowRun>,
 ) {
  /**

ontrack-extension-github/src/main/java/net/nemerosa/ontrack/extension/github/workflow/ValidationRunGitHubWorkflowJobProperty.kt

@@ -14,12 +14,18 @@ import net.nemerosa.ontrack.model.annotations.APIDescription
  * @property event Event having led to the creation of this validation
  */
 class ValidationRunGitHubWorkflowJobProperty(
+ @APIDescription("ID of the run")
  val runId: Long,
+ @APIDescription("Link to the GitHub Workflow run")
  val url: String,
+ @APIDescription("Name of the workflow")
  val name: String,
+ @APIDescription("Number of the run")
  val runNumber: Int,
- val job: String,
+ @APIDescription("True if the run is still flagged as running")
  val running: Boolean,
  @APIDescription("Event having led to the creation of this validation")
  val event: String?,
+ @APIDescription("Name of the workflow job which created this validation")
+ val job: String,
 )

ontrack-extension-github/src/main/resources/static/extension/github/property/net.nemerosa.ontrack.extension.github.workflow.BuildGitHubWorkflowRunPropertyType.tpl.html

@@ -1,2 +1,4 @@
-<a href="{{property.value.url}}">{{ property.value.name }}#{{ property.value.runNumber }}</a> <code>{{ property.value.event }}</code>
-<span ng-if="property.value.running"><em>(running)</em></span>
+<p ng-repeat="workflow in property.value.workflows">
+ <a href="{{workflow.url}}">{{ workflow.name }}#{{ workflow.runNumber }}</a> <code>{{ workflow.event }}</code>
+ <span ng-if="workflow.running"><em>(running)</em></span>
+</p>

ontrack-model/src/main/java/net/nemerosa/ontrack/model/docs/DocumentationUtils.kt

@@ -62,12 +62,7 @@ fun getFieldsForDocumentationClass(documentationClass: KClass<*>): List<FieldDoc
 
 fun getFieldsDocumentation(type: KClass<*>, section: String = ""): List<FieldDocumentation> {
  val documentationAnnotation = type.findAnnotations<Documentation>().firstOrNull { it.section == section }
- val documentationClass = documentationAnnotation?.value
- ?: if (type.hasAnnotation<SelfDocumented>()) {
- type
- } else {
- return emptyList()
- }
+ val documentationClass = documentationAnnotation?.value ?: type
  return getFieldsForDocumentationClass(documentationClass)
 }
 

ontrack-model/src/main/java/net/nemerosa/ontrack/model/support/NameValue.kt

@@ -4,8 +4,8 @@ import net.nemerosa.ontrack.model.annotations.APIDescription
 
 @APIDescription("Association of a name with a value")
 data class NameValue(
-  @APIDescription("Name of the pair")
-  val name: String,
-  @APIDescription("Value of the pair")
-  val value: String,
+ @APIDescription("Name")
+ val name: String,
+ @APIDescription("Value")
+ val value: String,
 )

ontrack-web-core/components/framework/properties/general.BuildLinkDisplayPropertyType/Display.js

@@ -0,0 +1,12 @@
+import {Descriptions, Space, Tag, Typography} from "antd";
+import TimestampText from "@components/common/TimestampText";
+import YesNo from "@components/common/YesNo";
+
+export default function Display({property}) {
+ return (
+ <Space>
+ <Typography.Text>Use label:</Typography.Text>
+ <YesNo strong={true} value={property.value.useLabel}/>
+ </Space>
+ )
+}

ontrack-web-core/components/framework/properties/general.BuildLinkDisplayPropertyType/Icon.js

@@ -0,0 +1,5 @@
+import {FaTag} from "react-icons/fa";
+
+export default function Icon() {
+ return <FaTag/>
+}

ontrack-web-core/components/framework/properties/git.branching.BranchingModelPropertyType/Display.js

@@ -0,0 +1,17 @@
+import {Descriptions, Typography} from "antd";
+
+export default function Display({property}) {
+
+ const items = property.value.patterns.map((pattern) => ({
+ key: pattern.name,
+ label: pattern.name,
+ children: <Typography.Text code>{pattern.value}</Typography.Text>,
+ span: 12,
+ }))
+
+ return (
+ <>
+ <Descriptions items={items} column={12}/>
+ </>
+ )
+}

ontrack-web-core/components/framework/properties/git.branching.BranchingModelPropertyType/Icon.js

@@ -0,0 +1,5 @@
+import {FaCodeBranch} from "react-icons/fa";
+
+export default function Icon() {
+ return <FaCodeBranch/>
+}

ontrack-web-core/components/framework/properties/github.workflow.BuildGitHubWorkflowRunPropertyType/Display.js

@@ -0,0 +1,32 @@
+import {Space, Spin, Typography} from "antd";
+import Link from "next/link";
+import {FaGithub} from "react-icons/fa";
+
+export default function Display({property}) {
+
+ return (
+ <>
+ <Space direction="vertical">
+ {
+ property.value.workflows.map(workflow => (
+ <>
+ <Space key={workflow.runId}>
+ <FaGithub/>
+ <Link href={workflow.url}>
+ {workflow.name}#{workflow.runNumber}
+ </Link>
+ {workflow.event && <Typography.Text code>{workflow.event}</Typography.Text>}
+ {
+ workflow.running && <>
+ <Spin size="small"/>
+ Running
+ </>
+ }
+ </Space>
+ </>
+ ))
+ }
+ </Space>
+ </>
+ )
+}

ontrack-web-core/components/framework/properties/github.workflow.BuildGitHubWorkflowRunPropertyType/Icon.js

@@ -0,0 +1,5 @@
+import {FaGithub} from "react-icons/fa";
+
+export default function Icon() {
+ return <FaGithub/>
+}

ontrack-web-core/components/framework/properties/github.workflow.ValidationRunGitHubWorkflowJobPropertyType/Display.js

@@ -0,0 +1,25 @@
+import {Space, Spin, Typography} from "antd";
+import Link from "next/link";
+import {FaGithub} from "react-icons/fa";
+
+export default function Display({property}) {
+
+ return (
+ <>
+ <Space key={property.value.runId}>
+ <FaGithub/>
+ <Link href={property.value.url}>
+ {property.value.name}#{property.value.runNumber}
+ </Link>
+ <Typography.Text code>{property.value.job}</Typography.Text>
+ {property.value.event && <Typography.Text code>{property.value.event}</Typography.Text>}
+ {
+ property.value.running && <>
+ <Spin size="small"/>
+ Running
+ </>
+ }
+ </Space>
+ </>
+ )
+}

ontrack-web-core/components/framework/properties/github.workflow.ValidationRunGitHubWorkflowJobPropertyType/Icon.js

@@ -0,0 +1,5 @@
+import {FaGithub} from "react-icons/fa";
+
+export default function Icon() {
+ return <FaGithub/>
+}

ontrack-web-core/components/framework/properties/jira.JIRAFollowLinksPropertyType/Display.js

@@ -0,0 +1,15 @@
+import {Tag} from "antd";
+
+export default function Display({property}) {
+ return (
+ <>
+ {
+ property.value.linkNames.map(link => (
+ <>
+ <Tag key={link}>{link}</Tag>
+ </>
+ ))
+ }
+ </>
+ )
+}

ontrack-web-core/components/framework/properties/jira.JIRAFollowLinksPropertyType/Icon.js

@@ -0,0 +1,5 @@
+import {FaJira} from "react-icons/fa";
+
+export default function Icon() {
+ return <FaJira/>
+}