Azure-devops-docs: Iterative insertion example is confusing

[letmaik]

The jobs parameter is an empty array. This is very confusing and it feels like the example is incomplete.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 6724abea-bbdc-bf66-ed5e-3214fa6c3e66
• Version Independent ID: 4f8dab21-3f0e-da32-cc0e-1d85c13c0065
• Content: Job and step templates - Azure Pipelines
• Content Source: docs/pipelines/process/templates.md
• Product: devops
• GitHub Login: @vtbassmatt
• Microsoft Alias: alewis

[vtbassmatt]

You're right. It's only showing the template part, and not showing how you'd actually use it. Until someone gets a chance to update the doc, here's a quick example.

First, the template straight from the docs:

# common-steps.yml
parameters:
  jobs: []

jobs:
- ${{ each job in parameters.jobs }}: # Each job
  - ${{ each pair in job }}:          # Insert all properties other than "steps"
      ${{ if ne(pair.key, 'steps') }}:
        ${{ pair.key }}: ${{ pair.value }}
    steps:                            # Wrap the steps
    - task: SetupMyBuildTools@1       # Pre steps
    - ${{ job.steps }}                # Users steps
    - task: PublishMyTelemetry@1      # Post steps
      condition: always()

Now, an example of using it:

# azure-pipelines.yml
jobs:
- template: common-steps.yml
  parameters:
    jobs:
    - job: BuildThing1
      pool: { vmImage: ubuntu-16.04 }
      steps:
      - script: my-build.sh --platform linux
    - job: BuildThing2
      pool: { vmImage: macos-10.13 }
      steps:
      - script: my-build.sh --platform macos

---

The resulting expanded pipeline will, at runtime, look like this:

    jobs:
    - job: BuildThing1
      pool: { vmImage: ubuntu-16.04 }
      steps:
      - task: SetupMyBuildTools@1  # inserted from template
      - script: my-build.sh --platform linux
      - task: PublishMyTelemetry@1  # inserted from template
        condition: always()
    - job: BuildThing2
      pool: { vmImage: macos-10.13 }
      steps:
      - task: SetupMyBuildTools@1  # inserted from template
      - script: my-build.sh --platform macos
      - task: PublishMyTelemetry@1  # inserted from template
        condition: always()

[cxwtool]

This issue hasn't been updated in more than 180 days, so we've closed it. If you feel the issue is still relevant and needs fixed, please reopen it and we'll take another look. We appreciate your feedback and apologize for any inconvenience.