Merge pull request #30566 from backstage/copilot/fix-30447-2

docs: Add prominent warnings about kebab-case action IDs causing NaN in scaffolder templates

docs/features/software-templates/adding-templates.md

@@ -49,7 +49,7 @@ spec:
 
   # here's the steps that are executed in series in the scaffolder backend
   steps:
-    - id: fetch-base
+    - id: fetchBase
       name: Fetch Base
       action: fetch:template
       input:
@@ -57,7 +57,7 @@ spec:
         values:
           name: ${{ parameters.name }}
 
-    - id: fetch-docs
+    - id: fetchDocs
       name: Fetch Docs
       action: fetch:plain
       input:

docs/features/software-templates/builtin-actions.md

@@ -78,7 +78,7 @@ allow most templates built for `fetch:cookiecutter` to work without any changes.
 
 ```yaml title="template.yaml"
 steps:
-   - id: fetch-base
+   - id: fetchBase
      name: Fetch Base
      # highlight-remove-next-line
      action: fetch:cookiecutter

docs/features/software-templates/experimental.md

@@ -100,7 +100,7 @@ metadata:
   name: my-template
 spec:
   EXPERIMENTAL_formDecorators:
-    - id: my-decorator
+    - id: myDecorator
       input:
         test: something funky
 
@@ -115,7 +115,7 @@ You can create a decorator using the simple helper method `createScaffolderFormD
 ```ts
 export const mockDecorator = createScaffolderFormDecorator({
   // give the decorator a name
-  id: 'mock-decorator',
+  id: 'mockDecorator',
 
   // define the schema for the input that can be provided in `template.yaml`
   schema: {

docs/features/software-templates/index.md

@@ -10,6 +10,16 @@ Components inside Backstage. By default, it has the ability to load skeletons of
 code, template in some variables, and then publish the template to some
 locations like GitHub or GitLab.
 
+:::warning Important
+
+When creating custom scaffolder actions, **use camelCase for action IDs** instead of kebab-case. Action IDs with dashes (like `fetch-component-id`) will cause template expressions like `${{ steps.fetch-component-id.output.componentId }}` to return `NaN` because the dashes are evaluated as subtraction operators in JavaScript expressions.
+
+:::note
+
+See the [Writing Custom Actions guide](./writing-custom-actions.md#naming-conventions) and [Template Migration guide](./migrating-from-v1beta2-to-v1beta3.md#watch-out-for-dash-case) for more details.
+
+:::
+
 ## Prerequisites
 
 :::note Note

docs/features/software-templates/writing-templates.md

@@ -59,7 +59,7 @@ spec:
 
   # here's the steps that are executed in series in the scaffolder backend
   steps:
-    - id: fetch-base
+    - id: fetchBase
       name: Fetch Base
       action: fetch:template
       input:
@@ -68,7 +68,7 @@ spec:
           name: ${{ parameters.name }}
           owner: ${{ parameters.owner }}
 
-    - id: fetch-docs
+    - id: fetchDocs
       name: Fetch Docs
       action: fetch:plain
       input:
@@ -87,7 +87,7 @@ spec:
       name: Register
       action: catalog:register
       input:
-        repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}
+        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
         catalogInfoPath: '/catalog-info.yaml'
 
   # some outputs which are saved along with the job for use in the frontend
@@ -622,7 +622,7 @@ The `steps` is an array of the things that you want to happen part of this
 template. These follow the same standard format:
 
 ```yaml
-- id: fetch-base # A unique id for the step
+- id: fetchBase # A unique id for the step
   name: Fetch Base # A title displayed in the frontend
   if: ${{ parameters.name }} # Optional condition, skip the step if not truthy
   each: ${{ parameters.iterable }} # Optional iterable, run the same step multiple times
@@ -633,6 +633,14 @@ template. These follow the same standard format:
       name: ${{ parameters.name }}
 ```
 
+:::warning Action ID Naming
+
+When using custom actions, **use camelCase for action IDs** to avoid issues with template expressions. Action IDs with dashes will cause expressions like `${{ steps.my-action.output.value }}` to return `NaN` instead of the expected value.
+
+Use `myAction` instead of `my-action`, or access outputs with bracket notation: `${{ steps['my-action'].output.value }}`.
+
+:::
+
 By default we ship some [built in actions](./builtin-actions.md) that you can
 take a look at, or you can
 [create your own custom actions](./writing-custom-actions.md).
@@ -724,7 +732,7 @@ spec:
           default: false
   ...
   steps:
-    - id: fetch-base
+    - id: fetchBase
       name: Fetch Base
       action: fetch:template
       input: