Versioning of software template

Author: pabel-rh

assemblies/assembly-configuring-templates.adoc

@@ -16,6 +16,7 @@ include::modules/customizing-templates/ref-creating-templates.adoc[leveloffset=+
 include::modules/customizing-templates/proc-creating-a-new-software-component-using-templates.adoc[leveloffset=+1]
 include::modules/customizing-templates/proc-searching-and-filtering-software-templates.adoc[leveloffset=+1]
 include::modules/customizing-templates/proc-adding-templates.adoc[leveloffset=+1]
+include::modules/customizing-templates/proc-versioning-software-templates.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources

modules/customizing-templates/proc-versioning-software-templates.adoc

@@ -0,0 +1,40 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-configuring-templates.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-versioning-software-templates_{context}"]
+= Versioning a Software Template in {product}
+
+As a platform administrator, you can version Software Templates by using the existing custom actions `catalog:scaffolded-from` and `catalog:template:version` within the scaffolder backend module. By using these custom actions, you can track the scaffolder template version and the corresponding version of the entities created from it, which improves lifecycle management.
+
+.Prerequisites
+
+* You have administrator rights to {product}.
+
+.Procedure
+
+To add versioning to a Software Template yaml file, modify the `catalog-info.yaml` file of the Software Template you want to update and do either of the following steps:
+
+* Include the `backstage.io/template-version` annotation in your template. When this annotation is present in your template, it will be automatically used to annotate your catalog entity.
+
+* Pass the `backstage.io/template-version` annotation as input to the action. This method takes precedence over the annotation in the template itself. It allows the user running the template to specify the version they wish to generate.
+
++
+[source,yaml]
+----
+# ...
+- id: version-templateRef
+  name: Append the version of this template to the entityRef
+  action: catalog:template:version
+  input:
+    annotations:
+      backstage.io/template-version: ${{ parameters.version }}
+# ...
+----
+
+.Verification
+
+. link:{configuring-book-url}#ref-creating-templates_configuring-templates[Create a component using the Software Template] that is updated for versioning.
+. In the *Catalog* page, select the newly created Software Template and click *VIEW SOURCE*.
+. In your GitHub page, go to your `catalog-info.yaml` file and you are able to see `backstage.io/template-version`.