diff --git a/.github/workflows/create-tfe-release-notes.yml b/.github/workflows/create-tfe-release-notes.yml index ff93e9b026..b0956d8d31 100644 --- a/.github/workflows/create-tfe-release-notes.yml +++ b/.github/workflows/create-tfe-release-notes.yml @@ -34,20 +34,20 @@ env: LAST_RELEASE_TAG: ${{ inputs.last-release-tag }} jobs: - copy-docs: - uses: ./.github/workflows/copy-cloud-docs-for-tfe.yml + sync-docs: + uses: ./.github/workflows/sync-docs-for-tfe.yml with: version: ${{ inputs.version }} secrets: inherit release-notes: - needs: copy-docs + needs: sync-docs runs-on: ubuntu-latest steps: - - name: Print outputs from copy-docs + - name: Print outputs from sync-docs run: | - echo "release_branch_name: ${{ needs.copy-docs.outputs.release_branch_name }}" - echo "diff_branch_pr_url: ${{ needs.copy-docs.outputs.diff_branch_pr_url }}" - echo "release_branch_pr_url: ${{ needs.copy-docs.outputs.release_branch_pr_url }}" + echo "release_branch_name: ${{ needs.sync-docs.outputs.release_branch_name }}" + echo "diff_branch_pr_url: ${{ needs.sync-docs.outputs.diff_branch_pr_url }}" + echo "release_branch_pr_url: ${{ needs.sync-docs.outputs.release_branch_pr_url }}" - name: Only run in hashicorp/web-unified-docs-internal run: | @@ -59,7 +59,7 @@ jobs: - name: Checkout web-unified-docs repository uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4 with: - ref: '${{ needs.copy-docs.outputs.release_branch_name }}' + ref: '${{ needs.sync-docs.outputs.release_branch_name }}' - name: Install and cache Ruby gems at root uses: ruby/setup-ruby@52753b7da854d5c07df37391a986c76ab4615999 # v1.191.0 @@ -74,7 +74,7 @@ jobs: - name: Turn branch into PR run: | - export RELEASE_BRANCH_NAME="${{ needs.copy-docs.outputs.release_branch_name }}" + export RELEASE_BRANCH_NAME="${{ needs.sync-docs.outputs.release_branch_name }}" RELEASE_NOTES_PR_URL=$(scripts/tfe-releases/ci/create-pull-request.sh) echo "RELEASE_NOTES_PR_URL=$RELEASE_NOTES_PR_URL" >> $GITHUB_ENV @@ -134,10 +134,10 @@ jobs: - ${{github.server_url}}/${{github.repository}}/actions/runs/${{github.run_id}} Changes since last release, diff PR: - - ${{ needs.copy-docs.outputs.diff_branch_pr_url }} + - ${{ needs.sync-docs.outputs.diff_branch_pr_url }} Release Notes PR: - - ${{ needs.copy-docs.outputs.release_branch_pr_url }} + - ${{ needs.sync-docs.outputs.release_branch_pr_url }} ❗ This is the Release PR that will be merged into main, once the release notes and diff PR are merged into it. ❗ @@ -149,5 +149,5 @@ jobs: git config --global user.email "team-rel-eng@hashicorp.com" git config --global user.name "tfe-release-bot" - gh pr edit ${{ needs.copy-docs.outputs.release_branch_pr_url }} \ + gh pr edit ${{ needs.sync-docs.outputs.release_branch_pr_url }} \ --body="${{env.docs_pr_body}}" diff --git a/.github/workflows/sync-docs-for-tfe.yml b/.github/workflows/sync-docs-for-tfe.yml new file mode 100644 index 0000000000..7a1f932055 --- /dev/null +++ b/.github/workflows/sync-docs-for-tfe.yml @@ -0,0 +1,119 @@ +name: Sync Cloud Docs For TFE + +on: + workflow_dispatch: + inputs: + version: + description: 'The TFE version for the upcoming TFE release, format is either vYYYYMM-# or MAJOR.MINOR.PATCH (without a "v" prefix).' + required: true + type: string + workflow_call: + inputs: + version: + description: 'The TFE version for the upcoming TFE release, format is either vYYYYMM-# or MAJOR.MINOR.PATCH (without a "v" prefix).' + required: true + type: string + outputs: + release_branch_name: + description: 'The name of the branch created for the new TFE version docs.' + value: ${{ jobs.sync-docs.outputs.release_branch_name }} + release_branch_pr_url: + description: 'The URL of the release branch created for the new TFE version docs.' + value: ${{ jobs.sync-docs.outputs.release_branch_pr_url }} + diff_branch_pr_url: + description: 'The URL of the diff branch created for the new TFE version docs.' + value: ${{ jobs.sync-docs.outputs.diff_branch_pr_url }} + +jobs: + sync-docs: + name: Sync Cloud Docs + runs-on: ubuntu-latest + outputs: + release_branch_name: ${{ steps.check-docs-pr.outputs.docs_branch_name }} + release_branch_pr_url: ${{ steps.check-docs-pr.outputs.release_branch_pr_url }} + diff_branch_pr_url: ${{ steps.update-diff-branch.outputs.diff_branch_pr_url }} + steps: + - name: Series/Release Summary + run: | + echo "# Summary" >> $GITHUB_STEP_SUMMARY + echo "**Workflow ref**: ${{github.ref_name}}" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "Triggered by branch creation (or manual workflow):" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "---" >> $GITHUB_STEP_SUMMARY + + - name: Checkout main for new docs version + uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4 + with: + path: '${{github.workspace}}/new-docs' + + - name: Check if new TFE version docs branch already exist + id: check-docs-pr + working-directory: '${{github.workspace}}/new-docs' + env: + docs_branch_name: tfe-release/${{inputs.version}} + diff_branch_name: HCPTF-diff/${{inputs.version}} + run: | + echo ${{ secrets.TFE_GITHUB_TOKEN }} | gh auth login --with-token + git config --global user.email "team-rel-eng@hashicorp.com" + git config --global user.name "tfe-release-bot" + + if [ "$(git ls-remote --heads origin ${{env.docs_branch_name}})" == "" ]; then + echo "❌ branch name ${{env.docs_branch_name}} does not exists, please run copy cloud docs for tfe workflow first to create the branch." + + echo "❌ branch name ${{env.docs_branch_name}} does not exists, please run copy cloud docs for tfe workflow first to create the branch." >> $GITHUB_STEP_SUMMARY + + exit 1 + fi + + if [ "$(git ls-remote --heads origin ${{env.diff_branch_name}})" == "" ]; then + echo "❌ branch name ${{env.diff_branch_name}} does not exists, please run copy cloud docs for tfe workflow first to create the branch." + + echo "❌ branch name ${{env.diff_branch_name}} does not exists, please run copy cloud docs for tfe workflow first to create the branch." >> $GITHUB_STEP_SUMMARY + + exit 1 + fi + + echo "docs_branch_name=${{env.docs_branch_name}}" >> $GITHUB_OUTPUT + docs_pr_url=$(gh pr view ${{env.docs_branch_name}} --json url --jq '.url') + echo "release_branch_pr_url=${docs_pr_url}" >> $GITHUB_OUTPUT + echo "**TFE Release PR URL**: ${docs_pr_url}" >> $GITHUB_STEP_SUMMARY + + - name: Generate version-metadata for workflow + working-directory: '${{github.workspace}}/new-docs' + run: | + npm i + npm run prebuild -- --only-build-version-metadata + + - name: Checkout HCPTF-diff for new docs version DIFF PR + uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4 + with: + path: '${{github.workspace}}/new-docs-diff-pr' + ref: 'HCPTF-diff/${{inputs.version}}' + + - name: Copy files for new docs version DIFF PR + uses: ./new-docs/.github/actions/copy-cloud-docs-for-tfe + with: + source_path: '${{github.workspace}}/new-docs' + target_path: '${{github.workspace}}/new-docs-diff-pr' + new_TFE_version: ${{inputs.version}} + + - name: Update existing docs version DIFF branch + id: update-diff-branch + working-directory: '${{github.workspace}}/new-docs-diff-pr' + env: + diff_branch_name: HCPTF-diff/${{inputs.version}} + run: | + echo ${{ secrets.TFE_GITHUB_TOKEN }} | gh auth login --with-token + git config --global user.email "team-rel-eng@hashicorp.com" + git config --global user.name "tfe-release-bot" + + git add . + git commit -m "HCP TF changes for TFE release" --no-verify || echo "No changes to commit" + git push origin HEAD + + diff_pr_url=$(gh pr view --json url --jq '.url') + echo "diff_branch_pr_url=${diff_pr_url}" >> $GITHUB_OUTPUT + echo "**Updated DIFF branch**: ${{env.diff_branch_name}}" >> $GITHUB_STEP_SUMMARY + echo "**TFE DIFF PR URL**: ${diff_pr_url}" >> $GITHUB_STEP_SUMMARY diff --git a/docs/workflows/infrastructure-group/publish-tfe-docs.md b/docs/workflows/infrastructure-group/publish-tfe-docs.md index 985e31859e..833e807ec8 100644 --- a/docs/workflows/infrastructure-group/publish-tfe-docs.md +++ b/docs/workflows/infrastructure-group/publish-tfe-docs.md @@ -6,6 +6,17 @@ This page describes the process for publishing Terraform Enterprise documentatio The team releases a milestone or major version once a quarter and releases patches as they become available. +## Artifacts for next major release + +After the release of a major verson, the release engineer runs a GitHub [workflow]((https://github.com/hashicorp/web-unified-docs-internal/actions/workflows/copy-cloud-docs-for-tfe.yml)) in the `web-unified-docs-internal` repository that creates the following artifacts: + +- A branch named `tfe-release/..x` for assembling the release notes and documentation updates. This is the branch that you merge into `main` to publish the docs. +- A branch named `HCPTF-diff/..x` that contains a diff of all of the new content from HCP TF slated for the next Terraform Enterprise release. This branch will be updated with latest changes before next release. +- A PR named `HCP TF changes for TFE release ..x` for merging content updates into the release notes into the assembly branch. Review this PR and merge into the assembly branch. +- A PR named `TFE Release ..x` for merging the release notes into the assembly branch. + +Refer to the [TFE Release 1.0.0](https://github.com/hashicorp/web-unified-docs-internal/pull/299) to see examples of the app deadline artifacts. + ## Get the release date Check the `#proj-tfe-releases` channel for a message from the team manager about important dates. For example: @@ -20,14 +31,7 @@ More details - Ask for the dates in the channel if it has been more than six weeks since the last milestone or major version and the manager hasn't posted the dates yet. You should also verify that the dates haven't changed closer to the standing date. -**Application Code Deadline**: Also called **app deadline**, this is the Terraform Enterprise code freeze and occurs 1.5 to 2 weeks before the release date. App deadline is also when the release engineer runs a GitHub workflow in the `web-unified-docs-internal` repository that creates the following artifacts: - -- A branch named `tfe-release/..x` for assembling the release notes and documentation updates. This is the branch that you merge into `main` to publish the docs. -- A branch named `HCPTF-diff/..x` that contains a diff of all of the new content from HCP TF slated for the next Terraform Enterprise release. -- A PR named `HCP TF changes for TFE release ..x` for merging content updates into the release notes into the assembly branch. Review this PR and merge into the assembly branch. -- A PR named `TFE Release ..x` for merging the release notes into the assembly branch. - -Refer to the [TFE Release 1.0.0](https://github.com/hashicorp/web-unified-docs-internal/pull/299) to see examples of the app deadline artifacts. +**Application Code Deadline**: Also called **app deadline**, this is the Terraform Enterprise code freeze and occurs 1.5 to 2 weeks before the release date. App deadline is also when the release engineer runs a GitHub [workflow]((https://github.com/hashicorp/web-unified-docs-internal/actions/workflows/create-tfe-release-notes.yml)) in the `web-unified-docs-internal` repository. The workkflow creates the release notes and updates the `HCPTF-diff/..x` branch with latest changes from terraform common docs. **Backport Deadline**: This is an engineering deadline and isn't actionable for IPG team members. @@ -62,7 +66,19 @@ This section contains supplementary information for publishing Terraform Enterpr ### Manually create docs artifacts for the release -The [Create TFE Release Notes](https://github.com/hashicorp/web-unified-docs-internal/actions/workflows/create-tfe-release-notes.yml) action creates the release notes PR and triggers the [Copy Cloud Docs For TFE](https://github.com/hashicorp/web-unified-docs-internal/actions/workflows/copy-cloud-docs-for-tfe.yml) action. These actions create the branches and PRs necessary for publishing a new version of the Terraform Enterprise documenation. Complete the following steps to manually run the actions: +#### Create the artifacts for next release + +The [Copy Cloud Docs For TFE](https://github.com/hashicorp/web-unified-docs-internal/actions/workflows/copy-cloud-docs-for-tfe.yml) action creates the branches and PRs necessary for publishing a new version of the Terraform Enterprise documenation. Complete the following steps to manually run the actions: + +1. Log into GitHub and navigate to the `web-unified-docs-internal` repository. +1. Click **Actions**, then choose **Copy Cloud Docs For TFE** from the **Actions** sidebar. +1. Open the **Run workflow** dropdown and choose the branch to use to run the workflow. This is `main` in almost all cases. +1. Specify the following values: + - Enter the upcoming version of the TFE release. + +#### Create the release notes PR + +The [Create TFE Release Notes](https://github.com/hashicorp/web-unified-docs-internal/actions/workflows/create-tfe-release-notes.yml) action creates the release notes PR. Complete the following steps to manually run the actions: 1. Log into GitHub and navigate to the `web-unified-docs-internal` repository. 1. Click **Actions**, then choose **Create TFE Release Notes** from the **Actions** sidebar.