feat(3128): Add docs for pipeline template job customization [3] (#599)

docs/ja/user-guide/configuration/sourceDirectory.md

@@ -8,7 +8,7 @@ toc:
       url: "#ソースディレクトリ"
 ---
 # ソースディレクトリ
-ソースディレクトリはパイプラインのベースとなるカスタムディレクトリを指定できます。ScrewdriverのUIでパイプラインを作成したときや、ディレクトリを追加するために現在のパイプラインをを更新するときに指定可能です。これは[monorepo](https://developer.atlassian.com/blog/2015/10/monorepos-in-git)のサブディレクトリに基づいてワークフローを実行する際に有用です。カスタムソースディレクトリを使えば、単一のリポジトリで複数パイプラインを作成することが可能です。
+ソースディレクトリはパイプラインのベースとなるカスタムディレクトリを指定できます。ScrewdriverのUIでパイプラインを作成したときや、ディレクトリを追加するために現在のパイプラインをを更新するときに指定可能です。これは[monorepo](https://www.atlassian.com/git/tutorials/monorepos)のサブディレクトリに基づいてワークフローを実行する際に有用です。カスタムソースディレクトリを使えば、単一のリポジトリで複数パイプラインを作成することが可能です。
 
 ### ソースディレクトリのフォーマット
 ディレクトリパスはリポジトリのルートからの相対パスとなります。ソースディレクトリの下には`screwdriver.yaml`が一つ有る必要があります。

docs/ja/user-guide/configuration/sourcePaths.md

@@ -10,7 +10,7 @@ toc:
 
 # ソースパス
 
-ソースパス機能を使うことで、特定のソースコードが更新された場合にのみジョブをトリガーすることができます。ジョブ定義の中で `sourcePaths` を文字列、または文字列の配列で設定することで利用できます。この機能は [monorepo](https://developer.atlassian.com/blog/2015/10/monorepos-in-git) のサブディレクトリに基づいたワークフローを実現するのに役立ちます。
+ソースパス機能を使うことで、特定のソースコードが更新された場合にのみジョブをトリガーすることができます。ジョブ定義の中で `sourcePaths` を文字列、または文字列の配列で設定することで利用できます。この機能は [monorepo](https://www.atlassian.com/git/tutorials/monorepos) のサブディレクトリに基づいたワークフローを実現するのに役立ちます。
 
 ### ソースパスの種類
 

docs/user-guide/configuration/sourceDirectory.md

@@ -9,7 +9,7 @@ toc:
 
 ---
 # Source Directory
-Source directory can be used to specify a custom directory that a pipeline is based upon. You can specify it when you create the pipeline in Screwdriver UI or update your current pipeline to add the directory. This can be useful for running workflows based on subdirectories in a [monorepo](https://developer.atlassian.com/blog/2015/10/monorepos-in-git). With custom source directory, now you can create multiple pipelines on a single repository.
+Source directory can be used to specify a custom directory that a pipeline is based upon. You can specify it when you create the pipeline in Screwdriver UI or update your current pipeline to add the directory. This can be useful for running workflows based on subdirectories in a [monorepo](https://www.atlassian.com/git/tutorials/monorepos). With custom source directory, now you can create multiple pipelines on a single repository.
 
 ### Source Directory format
 The directory path is relative to the root of the repository. You must have a `screwdriver.yaml` under your source directory.

docs/user-guide/configuration/sourcePaths.md

@@ -9,7 +9,7 @@ toc:
 
 ---
 # Source Paths
-Source paths can be used to specify source code paths that will trigger a job upon modification. This is done by using a `sourcePaths` keyword in your job definition as a string or array of strings. This can be useful for running workflows based on subdirectories in a [monorepo](https://developer.atlassian.com/blog/2015/10/monorepos-in-git).
+Source paths can be used to specify source code paths that will trigger a job upon modification. This is done by using a `sourcePaths` keyword in your job definition as a string or array of strings. This can be useful for running workflows based on subdirectories in a [monorepo](https://www.atlassian.com/git/tutorials/monorepos).
 
 ### Types of source paths
 You can either specify subdirectories and/or specific files as source paths. To denote a subdirectory, leave a trailing slash (`/`) at the end. The path is relative to the root of the repository.

docs/user-guide/templates/job-templates.md

@@ -220,6 +220,7 @@ jobs:
         requires: [~pr, ~commit]
         image: node:lts
     main2:
+        template: sd/noop@latest
         annotations:
             screwdriver.cd/mergeSharedSteps: true
         requires: [main]
@@ -239,6 +240,7 @@ jobs:
              - pretest: npm lint
              - test: npm test
     main2:
+        template: sd/noop@latest
         annotations:
              screwdriver.cd/mergeSharedSteps: true
         requires: [main]

docs/user-guide/templates/pipeline-templates.md

@@ -8,8 +8,11 @@ toc:
       url: "#pipeline-templates"
     - title: Finding templates
       url: "#finding-pipeline-templates"
-    - title: Using a template
+    - title: Using a pipeline template
       url: "#using-a-pipeline-template"
+    - title: Customization
+      url: "#customization"
+      subitem: true
     - title: Example pipeline template
       url: "#example-pipeline-template"
     - title: "Version/Tag Semantics"
@@ -85,6 +88,90 @@ If no template version is specified, the most recently published will be used. T
 
 The most reliable way to avoid unexpected template changes is to refer to a specific version of the template. For instance, `nodejs/[email protected]` is an immutable reference to a particular list of steps. Using a reference such as `nodejs/[email protected]` means that a job will automatically use `nodejs/[email protected]` when it becomes available, but that comes with risk of an unexpected change in behavior.
 
+### Customization
+Some customization can be done within the `jobs` configuration when using a Pipeline Template.
+
+For user-defined jobs with names that *already exist* in the pipeline template, customization is limited to a set of certain fields: `image`, `settings`, `environment`, and `requires`.
+
+For user-defined jobs with names that *do not already exist* in the pipeline template, all jobs fields are allowed.
+
+#### Example
+Given a pipeline template:
+
+```
+shared:
+  image: node:lts
+  environment:
+    VAR1: "one"
+    VAR2: "two"
+  steps:
+    - init: npm install
+    - test: npm test
+  settings:
+    email: [[email protected], [email protected]]
+    slack: 'mychannel'
+jobs:
+  main:
+    requires: [~pr, ~commit]
+  second:
+    requires: [main]
+```
+
+And user defined yaml:
+
+```
+template: sd-test/example-template@latest
+jobs:
+  main:
+    requires: [~commit]
+    image: node:20
+    settings:
+      email: [[email protected], [email protected]]
+    environment:
+      VAR3: "three"
+      VAR1: "empty"
+  third:
+    requires: []
+    image: node:lts
+    steps:
+      - echo: echo third job
+```
+
+Resulting config would be:
+```
+jobs:
+  main:
+    requires: [~commit]
+    image: node:20
+    steps:
+      - init: npm install
+      - test: npm test
+    environment:
+      VAR1: "empty"
+      VAR2: "two"
+      VAR3: "three"
+    settings:
+      email: [[email protected], [email protected]]
+      slack: 'mychannel'
+  second:
+    requires: [main]
+    image: node:lts
+    steps:
+      - init: npm install
+      - test: npm test
+    environment:
+      VAR1: "one"
+      VAR2: "two"
+    settings:
+      email: [[email protected], [email protected]]
+      slack: 'mychannel'
+  third:
+    requires: []
+    image: node:lts
+    steps:
+      - echo: echo third job
+```
+
 ## Version/Tag Semantics
 
 Template versions can be referenced in a variety of ways that express users' trade-off between an unchanging set of steps and automatically using improvements that a template's maintainers have added. As above, these examples reference nodejs/test template.
@@ -113,14 +200,14 @@ shared:
   environment:
     FOO: bar
 jobs:
-    main:
-      image: node:lts
-      requires: [~pr, ~commit]
-      steps:
-        - install: npm install
-        - test: npm test
-      secrets:
-        - NPM_TOKEN
+  main:
+    image: node:lts
+    requires: [~pr, ~commit]
+    steps:
+      - install: npm install
+      - test: npm test
+    secrets:
+      - NPM_TOKEN
 ```
 
 ## Creating a template
@@ -172,27 +259,27 @@ Example `screwdriver.yaml`:
 
 ```yaml
 shared:
-    image: node:lts
+  image: node:lts
 jobs:
   main:
-      requires: [~pr, ~commit]
-      steps:
-        - validate: npx -y -p screwdriver-template-main pipeline-template-validate
-      environment:
-        SD_TEMPLATE_PATH: ./path/to/template.yaml
+    requires: [~pr, ~commit]
+    steps:
+      - validate: npx -y -p screwdriver-template-main pipeline-template-validate
+    environment:
+      SD_TEMPLATE_PATH: ./path/to/template.yaml
   publish:
-      requires: [main]
-      steps:
-        - publish: npx -y -p screwdriver-template-main pipeline-template-publish
-        - tag: npx -y -p screwdriver-template-main pipeline-template-tag --namespace myNamespace --name template_name --version 1.3.0 --tag stable
-      environment:
-        SD_TEMPLATE_PATH: ./path/to/template.yaml
+    requires: [main]
+    steps:
+      - publish: npx -y -p screwdriver-template-main pipeline-template-publish
+      - tag: npx -y -p screwdriver-template-main pipeline-template-tag --namespace myNamespace --name template_name --version 1.3.0 --tag stable
+    environment:
+      SD_TEMPLATE_PATH: ./path/to/template.yaml
   remove:
-      steps:
-        - remove: npx -y -p screwdriver-template-main pipeline-template-remove --namespace myNamespace --name template_name
+    steps:
+      - remove: npx -y -p screwdriver-template-main pipeline-template-remove --namespace myNamespace --name template_name
   remove_tag:
-      steps:
-        - remove_tag: npx -y -p screwdriver-template-main pipeline-template-remove-tag --namespace myNamespace --name template_name --tag stable
+    steps:
+      - remove_tag: npx -y -p screwdriver-template-main pipeline-template-remove-tag --namespace myNamespace --name template_name --tag stable
 ```
 
 Create a Screwdriver pipeline with your template repo and start the build to validate and publish it.