From 9deaec2e0aa235917cec9ef465483e5e3587362c Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Mon, 11 Aug 2025 20:58:07 +0530 Subject: [PATCH 1/4] Versioning of software template --- .../assembly-configuring-templates.adoc | 1 + .../proc-versioning-software-templates.adoc | 40 +++++++++++++++++++ 2 files changed, 41 insertions(+) create mode 100644 modules/customizing-templates/proc-versioning-software-templates.adoc diff --git a/assemblies/assembly-configuring-templates.adoc b/assemblies/assembly-configuring-templates.adoc index 5d69a69b47..057396db7b 100644 --- a/assemblies/assembly-configuring-templates.adoc +++ b/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 diff --git a/modules/customizing-templates/proc-versioning-software-templates.adoc b/modules/customizing-templates/proc-versioning-software-templates.adoc new file mode 100644 index 0000000000..99b4994f38 --- /dev/null +++ b/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`. \ No newline at end of file From 9b5e8cc0b8fd275d0f28c0eaa78e5666901e92c9 Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Wed, 13 Aug 2025 11:14:27 +0530 Subject: [PATCH 2/4] Incorporated Aleksandr's comments --- .../proc-versioning-software-templates.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/customizing-templates/proc-versioning-software-templates.adoc b/modules/customizing-templates/proc-versioning-software-templates.adoc index 99b4994f38..2af7cdf522 100644 --- a/modules/customizing-templates/proc-versioning-software-templates.adoc +++ b/modules/customizing-templates/proc-versioning-software-templates.adoc @@ -14,7 +14,7 @@ As a platform administrator, you can version Software Templates by using the exi .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: +To add versioning to a Software Template yaml file, modify the Software Template that 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. From c936969f542535dfde0502869e184b519aa6f407 Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Thu, 14 Aug 2025 13:46:02 +0530 Subject: [PATCH 3/4] Incorporated tech comments --- .../proc-versioning-software-templates.adoc | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/modules/customizing-templates/proc-versioning-software-templates.adoc b/modules/customizing-templates/proc-versioning-software-templates.adoc index 2af7cdf522..6dbfacf0c2 100644 --- a/modules/customizing-templates/proc-versioning-software-templates.adoc +++ b/modules/customizing-templates/proc-versioning-software-templates.adoc @@ -14,10 +14,11 @@ As a platform administrator, you can version Software Templates by using the exi .Procedure -To add versioning to a Software Template yaml file, modify the Software Template that 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. +To add versioning to a Software Template yaml file, complete the following steps: +. Modify the Software Template that you want to update. +. Complete one or both of the following tasks: +* Include the `backstage.io/template-version` annotation in your template. When this annotation is present in your template, it is automatically used to annotate your catalog entity and a default version value is displayed. * 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. + @@ -34,7 +35,10 @@ To add versioning to a Software Template yaml file, modify the Software Template ---- .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`. \ No newline at end of file +. link:{configuring-book-url}#ref-creating-templates_configuring-templates[Create a catalog component using the updated Software Template]. This step creates a new component in Backstage and optionally, pushes files to an external repository (For example, GitHub, GitLab). +. Check the component in the Catalog UI. +.. On the *Catalog* page, locate the newly created catalog component. +.. Verify that the `backstage.io/template-version` annotation is present in the entity. You can use *INSPECT ENTITY* and select *YAML Raw* or *JSON Raw* view to find the annotation in the component definition. +. Only if you have published the catalog component: Check the component file in the repository. +.. If *VIEW SOURCE* is present in your UI: Click *VIEW SOURCE* to open the stored component file in the repository. +.. Locate the file manually and verify that the `backstage.io/template-version` annotation is present. \ No newline at end of file From f580dfb446316b8e5e81c4181f70fbc3c1e6a9e5 Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Mon, 18 Aug 2025 11:06:04 +0530 Subject: [PATCH 4/4] Incorporated Gerry's minor comment --- .../proc-versioning-software-templates.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/customizing-templates/proc-versioning-software-templates.adoc b/modules/customizing-templates/proc-versioning-software-templates.adoc index 6dbfacf0c2..35b55b0ca1 100644 --- a/modules/customizing-templates/proc-versioning-software-templates.adoc +++ b/modules/customizing-templates/proc-versioning-software-templates.adoc @@ -35,7 +35,7 @@ To add versioning to a Software Template yaml file, complete the following steps ---- .Verification -. link:{configuring-book-url}#ref-creating-templates_configuring-templates[Create a catalog component using the updated Software Template]. This step creates a new component in Backstage and optionally, pushes files to an external repository (For example, GitHub, GitLab). +. link:{configuring-book-url}#ref-creating-templates_configuring-templates[Create a catalog component using the updated Software Template]. This step creates a new component in {product-custom-resource-type} and optionally, pushes files to an external repository (For example, GitHub, GitLab). . Check the component in the Catalog UI. .. On the *Catalog* page, locate the newly created catalog component. .. Verify that the `backstage.io/template-version` annotation is present in the entity. You can use *INSPECT ENTITY* and select *YAML Raw* or *JSON Raw* view to find the annotation in the component definition.