From 139df252662fc95cd6d5c7b058b17e7eba54c785 Mon Sep 17 00:00:00 2001 From: Damien Coraboeuf Date: Thu, 2 Jan 2025 15:44:51 +0100 Subject: [PATCH] #1369 `sourceBuild` in the templating context for auto-versioning --- .../docs/asciidoc/appendix-templating.adoc | 4 +- .../events/event-auto-versioning-error.adoc | 2 +- ...auto-versioning-post-processing-error.adoc | 2 +- ...uto-versioning-pr-merge-timeout-error.adoc | 2 +- .../events/event-auto-versioning-success.adoc | 2 +- .../contexts/auto-versioning-context.adoc | 51 +++++++++++++++++++ .../asciidoc/templating/contexts/index.adoc | 10 ++++ .../renderables/templating-renderable-av.adoc | 2 +- .../templating-renderable-workflow.adoc | 2 +- .../templating-renderable-workflowInfo.adoc | 2 +- .../AutoVersioningTemplatingServiceImpl.kt | 15 ++++++ .../boot/docs/DocumentationGenerationIT.kt | 2 +- 12 files changed, 87 insertions(+), 9 deletions(-) create mode 100644 ontrack-docs/src/docs/asciidoc/templating/contexts/auto-versioning-context.adoc create mode 100644 ontrack-docs/src/docs/asciidoc/templating/contexts/index.adoc diff --git a/ontrack-docs/src/docs/asciidoc/appendix-templating.adoc b/ontrack-docs/src/docs/asciidoc/appendix-templating.adoc index edc5634856..cd229aa82e 100644 --- a/ontrack-docs/src/docs/asciidoc/appendix-templating.adoc +++ b/ontrack-docs/src/docs/asciidoc/appendix-templating.adoc @@ -55,10 +55,12 @@ For example, when using <>, it all depends on the _ To see the list of possible events and their contexts, see <>. -The next sections list the available sources, functions and filters. +The next sections list the available sources, functions, contexts and filters. There are also special objects, known as _templating renderable_, which are specific to some contexts, like <> or <>. +include::templating/contexts/index.adoc[] + include::templating/sources/index.adoc[] include::templating/functions/index.adoc[] diff --git a/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-error.adoc b/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-error.adoc index d0756fd4e5..53e78ebdc9 100644 --- a/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-error.adoc +++ b/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-error.adoc @@ -7,7 +7,7 @@ Context: * `project` - project - Target project * `branch` - branch - Target branch -* `xProject` - project - Dependency/source project +* `xPromotionRun` - promotion run - Source promotion run * `VERSION` - string - Version being set * `MESSAGE` - string - Auto versioning message * `ERROR` - string - Error message diff --git a/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-post-processing-error.adoc b/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-post-processing-error.adoc index 98057f5953..373f952fa1 100644 --- a/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-post-processing-error.adoc +++ b/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-post-processing-error.adoc @@ -7,7 +7,7 @@ Context: * `project` - project - Target project * `branch` - branch - Target branch -* `xProject` - project - Dependency/source project +* `xPromotionRun` - promotion run - Source promotion run * `VERSION` - string - Version being set * `MESSAGE` - string - Auto versioning message * `LINK` - string - Link to the post processing process diff --git a/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-pr-merge-timeout-error.adoc b/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-pr-merge-timeout-error.adoc index f9cf1f9530..c69687ce02 100644 --- a/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-pr-merge-timeout-error.adoc +++ b/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-pr-merge-timeout-error.adoc @@ -7,7 +7,7 @@ Context: * `project` - project - Target project * `branch` - branch - Target branch -* `xProject` - project - Dependency/source project +* `xPromotionRun` - promotion run - Source promotion run * `VERSION` - string - Version being set * `PR_NAME` - string - Title of the PR having been created * `PR_LINK` - string - Link to the PR having been created diff --git a/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-success.adoc b/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-success.adoc index 585a1b66ec..eb2f2d4f8e 100644 --- a/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-success.adoc +++ b/ontrack-docs/src/docs/asciidoc/events/event-auto-versioning-success.adoc @@ -7,7 +7,7 @@ Context: * `project` - project - Target project * `branch` - branch - Target branch -* `xProject` - project - Dependency/source project +* `xPromotionRun` - promotion run - Source promotion run * `VERSION` - string - Version being set * `MESSAGE` - string - Auto versioning message * `PR_NAME` - string - Title of the PR having been created diff --git a/ontrack-docs/src/docs/asciidoc/templating/contexts/auto-versioning-context.adoc b/ontrack-docs/src/docs/asciidoc/templating/contexts/auto-versioning-context.adoc new file mode 100644 index 0000000000..5b12f5eeee --- /dev/null +++ b/ontrack-docs/src/docs/asciidoc/templating/contexts/auto-versioning-context.adoc @@ -0,0 +1,51 @@ +[[appendix-templating-contexts-auto-versioning]] +===== Auto-versioning context + +For the templates used during an auto-versioning process (post-processing parameters, pull request templates, etc.), the following root contexts are available: + +|=== +|Context |Type |Description + +|`sourceProject` +|Project +|Reference to the project where the promotion was done + +|`targetBranch` +|Branch +|Branch being updated + +|`sourceBuild` +|Build +|Build which has been promoted + +|`sourcePromotionRun` +|Promotion run +|Promotion object + +|`PROMOTION` +|String +|Name of the promotion + +|`PATH` +|String +|_First_ path being updated + +|`PATHS` +|String +|Comma-separated list of all paths being updated + +|`PROPERTY` +|String +|Target property being updated + +|`VERSION` +|String +|Version being set + +| `av` +| See <> +| Specific object for the auto-versioning + +|=== + +// The source code is at AutoVersioningTemplatingServiceImpl \ No newline at end of file diff --git a/ontrack-docs/src/docs/asciidoc/templating/contexts/index.adoc b/ontrack-docs/src/docs/asciidoc/templating/contexts/index.adoc new file mode 100644 index 0000000000..d5247a11d7 --- /dev/null +++ b/ontrack-docs/src/docs/asciidoc/templating/contexts/index.adoc @@ -0,0 +1,10 @@ +[[appendix-templating-contexts-index]] +==== Execution contexts + +Different root contexts are available for the template expressions, depending on the context in which the template is executed. + +For a notification, the template is always executed in regard to an _event_. Each event provides its own list of root contexts. See the <>. + +There are several specific contexts: + +include::auto-versioning-context.adoc[] diff --git a/ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-av.adoc b/ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-av.adoc index 83476fc7c7..225e588692 100644 --- a/ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-av.adoc +++ b/ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-av.adoc @@ -1,5 +1,5 @@ [[templating-renderable-av]] -==== Auto-versioning context (av) +===== Auto-versioning context (av) The `av` context can be used in templates in the PR title & body templates, in order to access information about the auto-versioning request. diff --git a/ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-workflow.adoc b/ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-workflow.adoc index 88a19f9121..d548b8e451 100644 --- a/ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-workflow.adoc +++ b/ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-workflow.adoc @@ -1,5 +1,5 @@ [[templating-renderable-workflow]] -==== Information about the workflow (workflow) +===== Information about the workflow (workflow) The `workflow` context is used to access information about the nodes of the workflow, in notifications or other templates rendered in the context of the workflow execution. diff --git a/ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-workflowInfo.adoc b/ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-workflowInfo.adoc index 0e9c6776be..3fa1a9e04e 100644 --- a/ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-workflowInfo.adoc +++ b/ontrack-docs/src/docs/asciidoc/templating/renderables/templating-renderable-workflowInfo.adoc @@ -1,5 +1,5 @@ [[templating-renderable-workflowInfo]] -==== Global information about the workflow (workflowInfo) +===== Global information about the workflow (workflowInfo) The `workflowInfo` context is used to access information about the workflow itself, in notifications or other templates rendered in the context of the workflow execution. diff --git a/ontrack-extension-auto-versioning/src/main/java/net/nemerosa/ontrack/extension/av/processing/AutoVersioningTemplatingServiceImpl.kt b/ontrack-extension-auto-versioning/src/main/java/net/nemerosa/ontrack/extension/av/processing/AutoVersioningTemplatingServiceImpl.kt index fec74ef5fb..989624ed59 100644 --- a/ontrack-extension-auto-versioning/src/main/java/net/nemerosa/ontrack/extension/av/processing/AutoVersioningTemplatingServiceImpl.kt +++ b/ontrack-extension-auto-versioning/src/main/java/net/nemerosa/ontrack/extension/av/processing/AutoVersioningTemplatingServiceImpl.kt @@ -35,12 +35,24 @@ class AutoVersioningTemplatingServiceImpl( ?: throw ProjectNotFoundException(order.sourceProject) } + val sourceBuild: Build? by lazy { + order.sourceBuildId?.let { + structureService.getBuild(ID.of(it)) + } + } + val sourcePromotionRun: PromotionRun? by lazy { order.sourcePromotionRunId?.let { structureService.getPromotionRun(ID.of(it)) } } + /** + * When adding new entries, please also update the documentation at + * + * ontrack-docs/src/docs/asciidoc/templating/contexts/auto-versioning-context.adoc + */ + val context: Map by lazy { val tmp = mutableMapOf( "sourceProject" to sourceProject, @@ -52,6 +64,9 @@ class AutoVersioningTemplatingServiceImpl( "VERSION" to order.targetVersion, "av" to AutoVersioningOrderTemplatingRenderable(order, currentVersions, sourceProject), ) + if (sourceBuild != null) { + tmp["sourceBuild"] = sourceBuild!! + } if (sourcePromotionRun != null) { tmp["sourcePromotionRun"] = sourcePromotionRun!! } diff --git a/ontrack-ui/src/test/java/net/nemerosa/ontrack/boot/docs/DocumentationGenerationIT.kt b/ontrack-ui/src/test/java/net/nemerosa/ontrack/boot/docs/DocumentationGenerationIT.kt index 878aff92e3..322e286f8e 100644 --- a/ontrack-ui/src/test/java/net/nemerosa/ontrack/boot/docs/DocumentationGenerationIT.kt +++ b/ontrack-ui/src/test/java/net/nemerosa/ontrack/boot/docs/DocumentationGenerationIT.kt @@ -65,7 +65,7 @@ class DocumentationGenerationIT : AbstractDocumentationGenerationTestSupport() { directoryContext.writeFile( fileId = fileId, - level = 4, + level = 5, title = getTRDTitle(trd), header = description, fields = emptyList(),