Split doc generation pipeline into parallel v1.0 and beta stages

azure-pipelines/common-templates/create-pr.yml

@@ -14,10 +14,14 @@ parameters:
   - name: Body
     type: string
     default: ""
+  - name: Condition
+    type: string
+    default: "succeeded()"
 
 steps:
   - task: PowerShell@2
     displayName: Create Pull Request for generated build
+    condition: ${{ parameters.Condition }}
     env:
       GhAppId: $(microsoft-graph-devx-bot-appid)
       GhAppKey: $(microsoft-graph-devx-bot-privatekey)

azure-pipelines/common-templates/generate-docs-steps.yml

@@ -0,0 +1,198 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+#
+# Reusable steps that generate the Microsoft Graph PowerShell reference docs for a
+# single SDK profile (v1.0 or beta), commit the result to a dedicated branch and
+# open a pull request for that profile. Consumed by the parallel stages in
+# powershell-docs.yml so that v1.0 and beta each produce an independent PR.
+
+parameters:
+  - name: GraphProfileFilter
+    type: string
+    values:
+      - v1.0
+      - beta
+  - name: BranchPrefix
+    type: string
+  - name: PrTitle
+    type: string
+  - name: PrBody
+    type: string
+    default: "This pull request was automatically created by Azure Pipelines. **Important** Check for unexpected deletions or changes in this PR."
+
+steps:
+  - template: ../update-template.yml
+  - task: PowerShell@2
+    name: "ComputeBranch"
+    displayName: 'Compute Branch Name'
+    inputs:
+      targetType: 'inline'
+      script: |
+        git submodule update --init --recursive
+        $branch = "{0}_{1}" -f "${{ parameters.BranchPrefix }}", (Get-Date -Format yyyyMMddHHmm)
+        Write-Host "Compute branch: $branch"
+        Write-Host "##vso[task.setvariable variable=WeeklyReferenceDocsBranch;isOutput=true]$branch"
+  - task: Bash@3
+    name: "CreateBranch"
+    displayName: "Create weekly refresh branch"
+    inputs:
+      targetType: inline
+      script: |
+        git status
+        git branch $(ComputeBranch.WeeklyReferenceDocsBranch)
+        git checkout $(ComputeBranch.WeeklyReferenceDocsBranch)
+        # Record the commit the branch was created from so the push step can tell
+        # whether generation actually advanced the branch (the generation scripts
+        # commit their own output, so the working tree is clean by push time).
+        BASE_COMMIT=$(git rev-parse HEAD)
+        echo "Base commit: $BASE_COMMIT"
+        echo "##vso[task.setvariable variable=BaseCommit;isOutput=true]$BASE_COMMIT"
+        git status
+  - task: PowerShell@2
+    displayName: 'Create missing external docs folder'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/CreateExternalDocsFolder.ps1
+  - task: PowerShell@2
+    displayName: 'Generate markdown files from PowerShell help files'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/GenerateMarkDown.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Escape disallowed html tags'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/EscapeDisallowedHtmlTags.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Update metadata header'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/MsSubserviceUpdate.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Generate permissions table'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/GeneratePermissionsTable.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Update Links'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/UpdateLinks.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+      errorActionPreference: 'stop'
+  - task: PowerShell@2
+    displayName: 'Repair Examples and Descriptions and Title'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/RepairExamplesDescriptionsAndTitle.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Remove boiler plate code'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/RemoveBoilerPlateCode.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Remove invalid fullstops'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/RemoveInvalidFullStops.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Generate missing docs for aliased cmdlets'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/GenerateAliasedDocs.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Correct related links section'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/CorrectRelatedLinks-AllFiles.ps1
+      arguments: -GraphProfileFilter '${{ parameters.GraphProfileFilter }}'
+  - task: PowerShell@2
+    displayName: 'Stabilize ms.date values'
+    continueOnError: false
+    inputs:
+      targetType: 'filePath'
+      pwsh: true
+      filePath: scripts/StabilizeMsDate.ps1
+      errorActionPreference: 'stop'
+  - task: AzureKeyVault@2
+    displayName: "Azure Key Vault: Get GitHub App secrets"
+    inputs:
+      azureSubscription: "Federated AKV Managed Identity Connection"
+      KeyVaultName: akv-prod-eastus
+      SecretsFilter: "microsoft-graph-devx-bot-appid,microsoft-graph-devx-bot-privatekey"
+  - task: PowerShell@2
+    name: "PushChanges"
+    displayName: Pushing to github
+    env:
+      GhAppId: $(microsoft-graph-devx-bot-appid)
+      GhAppKey: $(microsoft-graph-devx-bot-privatekey)
+    inputs:
+      targetType: inline
+      pwsh: true
+      script: |
+        git config --global user.email "GraphTooling@service.microsoft.com"
+        git config --global user.name "Microsoft Graph DevX Tooling"
+        git config --system core.longpaths true
+        # Commit anything the formatting steps left behind. The generation scripts
+        # already commit their own output, so this may legitimately be a no-op.
+        git add .
+        if (-not [string]::IsNullOrWhiteSpace((git status --porcelain))) {
+          git commit -m "Updating reference docs"
+        }
+        # Detect real changes by comparing the branch tip to the commit it was created
+        # from. Checking the working tree is not enough because earlier steps already
+        # committed their output, leaving the tree clean but the branch ahead of base.
+        $baseCommit = "$(CreateBranch.BaseCommit)"
+        $headCommit = (git rev-parse HEAD).Trim()
+        if ($headCommit -eq $baseCommit) {
+          Write-Host "No documentation changes detected (branch is at its base commit); skipping push and pull request."
+          Write-Host "##vso[task.setvariable variable=HasChanges;isOutput=true]false"
+          return
+        }
+        # The microsoft-graph-devx-bot GitHub App must have contents:write on this repo.
+        $token = & "$(Build.SourcesDirectory)/scripts/Generate-Github-Token.ps1" -AppClientId $env:GhAppId -AppPrivateKeyContents $env:GhAppKey -Repository "MicrosoftDocs/microsoftgraph-docs-powershell"
+        if ([string]::IsNullOrWhiteSpace($token)) { throw "Failed to generate GitHub App installation token." }
+        # Mask the token so it is never surfaced in pipeline logs.
+        Write-Host "##vso[task.setsecret]$token"
+        # A GitHub App installation token authenticates over HTTPS as user "x-access-token".
+        $pushUrl = "https://x-access-token:$token@github.com/MicrosoftDocs/microsoftgraph-docs-powershell.git"
+        git push --set-upstream $pushUrl $(ComputeBranch.WeeklyReferenceDocsBranch)
+        if ($LASTEXITCODE -ne 0) { throw "git push failed with exit code $LASTEXITCODE." }
+        Write-Host "##vso[task.setvariable variable=HasChanges;isOutput=true]true"
+  - template: create-pr.yml
+    parameters:
+      BaseBranch: "main"
+      TargetBranch: $(ComputeBranch.WeeklyReferenceDocsBranch)
+      Title: "${{ parameters.PrTitle }}"
+      Body: "${{ parameters.PrBody }}"
+      Condition: "and(succeeded(), eq(variables['PushChanges.HasChanges'], 'true'))"

azure-pipelines/powershell-docs.yml

@@ -47,156 +47,41 @@ extends:
     customBuildTags:
     - ES365AIMigrationTooling
     stages:
-    - stage: stage
+    - stage: GenerateV1
+      displayName: 'Generate v1.0 reference docs'
+      dependsOn: []
       jobs:
-      - job: PowerShellDocsUpdate
+      - job: PowerShellDocsUpdateV1
         timeoutInMinutes: ${{ parameters.PipelineTimeout }}
         templateContext:
           outputs:
           - output: pipelineArtifact
             displayName: 'Publish Examples to be reviewed as artifact'
             targetPath: missingexternaldocsurl
-            artifactName: 'MissingExternalDocs'
+            artifactName: 'MissingExternalDocs-v1.0'
             publishLocation: 'Container'
         steps:
-        - template: azure-pipelines/update-template.yml@self
-        - task : PowerShell@2
-          name: "ComputeBranch"
-          displayName: 'Compute Branch Name'
-          inputs:
-            targetType: 'inline'
-            script: |
-              git submodule update --init --recursive
-              $branch = "{0}_{1}" -f "WeeklyReferenceDocsUpdate", (Get-Date -Format yyyyMMddHHmm)
-              Write-Host "Compute branch: $branch"
-              Write-Host "##vso[task.setvariable variable=WeeklyReferenceDocsBranch;isOutput=true]$branch"
-        - task: Bash@3
-          displayName: "Create weekly refresh branch"
-          inputs:
-            targetType: inline
-            script: |
-              git status
-              git branch $(ComputeBranch.WeeklyReferenceDocsBranch)
-              git checkout $(ComputeBranch.WeeklyReferenceDocsBranch)
-              git status              
-        - task: PowerShell@2
-          displayName: 'Create missing external docs folder'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/CreateExternalDocsFolder.ps1
-
-        - task: PowerShell@2
-          displayName: 'Generate markdown files from PowerShell help files'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/GenerateMarkDown.ps1
-        - task: PowerShell@2
-          displayName: 'Escape disallowed html tags'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/EscapeDisallowedHtmlTags.ps1
-        - task: PowerShell@2
-          displayName: 'Update metadata header'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/MsSubserviceUpdate.ps1
-        - task: PowerShell@2
-          displayName: 'Generate permissions table'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/GeneratePermissionsTable.ps1
-        - task: PowerShell@2
-          displayName: 'Update Links'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/UpdateLinks.ps1
-            errorActionPreference: 'stop'
-        - task: PowerShell@2
-          displayName: 'Repair Examples and Descriptions and Title'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/RepairExamplesDescriptionsAndTitle.ps1
-        - task: PowerShell@2
-          displayName: 'Remove boiler plate code'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/RemoveBoilerPlateCode.ps1
-        - task: PowerShell@2
-          displayName: 'Remove invalid fullstops'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/RemoveInvalidFullStops.ps1
-        - task: PowerShell@2
-          displayName: 'Generate missing docs for aliased cmdlets'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/GenerateAliasedDocs.ps1
-        - task: PowerShell@2
-          displayName: 'Correct related links section'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/CorrectRelatedLinks-AllFiles.ps1
-        - task: PowerShell@2
-          displayName: 'Stabilize ms.date values'
-          continueOnError: false
-          inputs:
-            targetType: 'filePath'
-            pwsh: true
-            filePath: scripts/StabilizeMsDate.ps1
-            errorActionPreference: 'stop'
-        - task: AzureKeyVault@2
-          displayName: "Azure Key Vault: Get GitHub App secrets"
-          inputs:
-            azureSubscription: "Federated AKV Managed Identity Connection"
-            KeyVaultName: akv-prod-eastus
-            SecretsFilter: "microsoft-graph-devx-bot-appid,microsoft-graph-devx-bot-privatekey"
-        - task: PowerShell@2
-          displayName: Pushing to github
-          env:
-            GhAppId: $(microsoft-graph-devx-bot-appid)
-            GhAppKey: $(microsoft-graph-devx-bot-privatekey)
-          inputs:
-            targetType: inline
-            pwsh: true
-            script: |
-              git config --global user.email "GraphTooling@service.microsoft.com"
-              git config --global user.name "Microsoft Graph DevX Tooling"
-              git config --system core.longpaths true
-              # The microsoft-graph-devx-bot GitHub App must have contents:write on this repo.
-              $token = & "$(Build.SourcesDirectory)/scripts/Generate-Github-Token.ps1" -AppClientId $env:GhAppId -AppPrivateKeyContents $env:GhAppKey -Repository "MicrosoftDocs/microsoftgraph-docs-powershell"
-              if ([string]::IsNullOrWhiteSpace($token)) { throw "Failed to generate GitHub App installation token." }
-              # Mask the token so it is never surfaced in pipeline logs.
-              Write-Host "##vso[task.setsecret]$token"
-              git status
-              git add .
-              git commit -m "Updating reference docs"
-              git push --set-upstream "https://x-access-token:$token@github.com/MicrosoftDocs/microsoftgraph-docs-powershell.git" $(ComputeBranch.WeeklyReferenceDocsBranch)
-              git status
-        - template: azure-pipelines/common-templates/create-pr.yml@self
+        - template: azure-pipelines/common-templates/generate-docs-steps.yml@self
           parameters:
-            BaseBranch: "main"
-            TargetBranch: $(ComputeBranch.WeeklyReferenceDocsBranch)
-            Title: "Weekly PowerShell Microsoft Graph Reference Docs Refresh"
-            Body: "This pull request was automatically created by Azure Pipelines. **Important** Check for unexpected deletions or changes in this PR."
+            GraphProfileFilter: 'v1.0'
+            BranchPrefix: 'WeeklyReferenceDocsUpdate-v1'
+            PrTitle: 'Weekly PowerShell Microsoft Graph v1.0 Reference Docs Refresh'
+    - stage: GenerateBeta
+      displayName: 'Generate beta reference docs'
+      dependsOn: []
+      jobs:
+      - job: PowerShellDocsUpdateBeta
+        timeoutInMinutes: ${{ parameters.PipelineTimeout }}
+        templateContext:
+          outputs:
+          - output: pipelineArtifact
+            displayName: 'Publish Examples to be reviewed as artifact'
+            targetPath: missingexternaldocsurl
+            artifactName: 'MissingExternalDocs-beta'
+            publishLocation: 'Container'
+        steps:
+        - template: azure-pipelines/common-templates/generate-docs-steps.yml@self
+          parameters:
+            GraphProfileFilter: 'beta'
+            BranchPrefix: 'WeeklyReferenceDocsUpdate-beta'
+            PrTitle: 'Weekly PowerShell Microsoft Graph beta Reference Docs Refresh'