#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/>
+}