#1369 sourceBuild in the templating context for auto-versioning

ontrack-docs/src/docs/asciidoc/appendix-templating.adoc

@@ -55,10 +55,12 @@ For example, when using <<notifications,notifications>>, it all depends on the _
 
 To see the list of possible events and their contexts, see <<appendix-events>>.
 
-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 <<auto-versioning>> or <<workflows>>.
 
+include::templating/contexts/index.adoc[]
+
 include::templating/sources/index.adoc[]
 
 include::templating/functions/index.adoc[]

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

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

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

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

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 <<templating-renderable-av>>
+| Specific object for the auto-versioning
+
+|===
+
+// The source code is at AutoVersioningTemplatingServiceImpl

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 <<appendix-event-index,list of events>>.
+
+There are several specific contexts:
+
+include::auto-versioning-context.adoc[]

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.
 

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.
 

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.
 

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<String, Any> 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!!
             }

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(),