From 7880902da9766521a841bd3a6eaaaae908794363 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 1d13cf8a53f55a16da368912f3391ac0bc7754c7 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 8db17768e1c2ea8dc2d613a032a6e11eacad3bd6 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 7de2f685214b85db523b12545dfc9d03344602d9 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.