Merge branch 'ramyaparimi/update-contributing-docs' of https://github.com/github/docs-internal into ramyaparimi/update-contributing-docs

.eslintignore

@@ -1 +0,0 @@
-storybook/

.github/PULL_REQUEST_TEMPLATE.md

@@ -20,7 +20,7 @@ Closes [issue link]
 
 ### What's being changed:
 
-<!-- Share artifacts of the changes, be they code snippets, GIFs or screenshots; whatever shares the most context. -->
+<!-- Share artifacts of the changes, be they code snippets, GIFs or screenshots; whatever shares the most context. If you made changes to the `content` directory, a table will populate in a comment below with the staging and live article links -->
 
 ### Check off the following:
 

.github/actions-scripts/enterprise-server-issue-templates/release-issue.md

@@ -47,13 +47,7 @@ If you aren't comfortable going through the steps alone, sync up with a docs eng
   ```
 
   **Note:** All of the content in this file will be updated when the release notes are created in the megabranch including the filename `PLACEHOLDER.yml`. You can update the date or leave it as-is and wait to update it when the release notes are finalized.
-- [ ] Create the search indices for the new release:
 
-  ```
-  npm run sync-search-ghes-release
-  ```
-
-  Check in the updated `lib/search/cached-index-names.json`.
 - [ ] (Optional) Add a Release Candidate banner:
 
   ```

.github/actions-scripts/fr-add-docs-reviewers-requests.js

@@ -133,7 +133,14 @@ async function run() {
   // Exclude existing items going forward.
   // Until we have a way to check from a PR whether the PR is in a project,
   // this is how we (roughly) avoid overwriting PRs that are already on the board
-  const newItemIDs = itemIDs.filter((id) => !existingItemIDs.includes(id))
+  let newItemIDs = []
+  let newItemAuthors = []
+  itemIDs.forEach((id, index) => {
+    if (!existingItemIDs.includes(id)) {
+      newItemIDs.push(id)
+      newItemAuthors.push(prAuthors[index])
+    }
+  })
 
   if (newItemIDs.length === 0) {
     console.log('All found PRs are already on the project. Exiting.')
@@ -145,11 +152,14 @@ async function run() {
   for (const [index, itemID] of newItemIDs.entries()) {
     const updateProjectNextItemMutation = generateUpdateProjectNextItemFieldMutation({
       item: itemID,
-      author: prAuthors[index],
+      author: newItemAuthors[index],
       turnaround: 2,
+      feature: 'OpenAPI schema update',
     })
-    const contributorType = isDocsTeamMember(prAuthors[index]) ? docsMemberTypeID : hubberTypeID
-    console.log(`Populating fields for item: ${itemID}`)
+    const contributorType = (await isDocsTeamMember(newItemAuthors[index]))
+      ? docsMemberTypeID
+      : hubberTypeID
+    console.log(`Populating fields for item: ${itemID} with author ${newItemAuthors[index]}`)
 
     await graphql(updateProjectNextItemMutation, {
       project: projectID,

.github/actions-scripts/openapi-schema-branch.js

@@ -36,7 +36,7 @@ const changedFiles = execSync('git diff --name-only HEAD').toString()
 if (changedFiles !== '') {
   console.log(`These files were changed:\n${changedFiles}`)
   console.log(
-    `🚧⚠️ Your decorated and dereferenced schema files don't match. Ensure you're using decorated and dereferenced schemas from the automatically created pull requests by the 'github-openapi-bot' user. For more information, see 'script/rest/README.md'. 🛑`
+    `🚧⚠️ Your decorated and dereferenced schema files don't match. Ensure you're using decorated and dereferenced schemas from the automatically created pull requests by the 'github-openapi-bot' user. \n\n If this test is failing after updates to the script/rest directory, run script/rest/update-files.js --decorate-only to re-generate the decorated files from the existing dereferenced files and check those in. \n\n If this test is failing after an update to a package, check the changes the new package makes to the decorated files by running script/rest/update-files.js --decorate-only. If the changes are small style changes that don't impact the overall experience, check the updated decorated file in. Otherwise, more work may be needed to be compatible with the updated package. \n\n For more information, see 'script/rest/README.md'. 🛑`
   )
   process.exit(1)
 }

.github/actions-scripts/ready-for-docs-review.js

@@ -66,7 +66,7 @@ async function run() {
 
   // Determine which variable to use for the contributor type
   let contributorType
-  if (isDocsTeamMember(process.env.AUTHOR_LOGIN)) {
+  if (await isDocsTeamMember(process.env.AUTHOR_LOGIN)) {
     contributorType = docsMemberTypeID
   } else if (process.env.PR_REPO === 'github/docs') {
     contributorType = osContributorTypeID

.github/allowed-actions.js

@@ -9,12 +9,14 @@ export default [
   'actions/labeler@5f867a63be70efff62b767459b009290364495eb', // v2.2.0
   'actions/setup-node@38d90ce44d5275ad62cc48384b3d8a58c500bb5f', // v2.2.0
   'actions/stale@9d6f46564a515a9ea11e7762ab3957ee58ca50da', // v3.0.16
+  'actions/upload-artifact@27121b0bdffd731efa15d66772be8dc71245d074', // v2.2.4
   'alex-page/github-project-automation-plus@fdb7991b72040d611e1123d2b75ff10eda9372c9',
   'andymckay/labeler@22d5392de2b725cea4b284df5824125054049d84',
   'crowdin/github-action@fd9429dd63d6c0f8a8cb4b93ad8076990bd6e688',
   'crykn/copy_folder_to_another_repo_action@0282e8b9fef06de92ddcae9fe6cb44df6226646c',
   'cschleiden/actions-linter@caffd707beda4fc6083926a3dff48444bc7c24aa', // uses github-actions-parser v0.23.0
-  'dawidd6/action-delete-branch@47743101a121ad657031e6704086271ca81b1911',
+  'dawidd6/action-delete-branch@47743101a121ad657031e6704086271ca81b1911', // v3.0.2
+  'dawidd6/action-download-artifact@b9571484721e8187f1fd08147b497129f8972c74', // v2.14.0
   'docker://chinthakagodawita/autoupdate-action:v1',
   'dorny/paths-filter@eb75a1edc117d3756a18ef89958ee59f9500ba58',
   'github/codeql-action/analyze@v1',
@@ -27,11 +29,13 @@ export default [
   'peter-evans/create-issue-from-file@b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e',
   'peter-evans/create-or-update-comment@5221bf4aa615e5c6e95bb142f9673a9c791be2cd',
   'peter-evans/create-pull-request@8c603dbb04b917a9fc2dd991dc54fef54b640b43',
+  'peter-evans/find-comment@0da1f4fc1f20cd898368bd56089d391df418f52f',
   'rachmari/actions-add-new-issue-to-column@1a459ef92308ba7c9c9dc2fcdd72f232495574a9',
   'rachmari/labeler@832d42ec5523f3c6d46e8168de71cd54363e3e2e',
   'repo-sync/github-sync@3832fe8e2be32372e1b3970bbae8e7079edeec88',
   'repo-sync/pull-request@33777245b1aace1a58c87a29c90321aa7a74bd7d',
   'someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd',
   'tjenkinson/gh-action-auto-merge-dependency-updates@4d7756c04d9d999c5968697a621b81c47f533d61',
+  'Bhacaz/checkout-files@c8f01756bfd894ba746d5bf48205e19000b0742b', // v1.0.0
   'EndBug/add-and-commit@2bdc0a61a03738a1d1bda24d566ad0dbe3083d87',
 ]

.github/workflows/check-all-english-links.yml

@@ -34,6 +34,15 @@ jobs:
       - name: Run script
         run: |
           script/check-english-links.js > broken_links.md
+
+      # check-english-links.js returns 0 if no links are broken, and 1 if any links
+      # are broken. When an Actions step's exit code is 1, the action run's job status
+      # is failure and the run ends. The following steps create an issue for the
+      # broken link report only if any links are broken, so `if: ${{ failure() }}`
+      # ensures the steps run desite though the previous step's failure of the job.
+      #
+      # https://docs.github.com/actions/reference/context-and-expression-syntax-for-github-actions#job-status-check-functions
+
       - if: ${{ failure() }}
         name: Get title for issue
         id: check
@@ -62,13 +71,14 @@ jobs:
           # Link to the previous report from the new report that triggered this
           # workflow run.
 
-          for issue_url in $(gh list-reports \
+          previous_report_url=$(gh list-reports \
                                   --state all \
                                   --limit 2 \
                                   --json url \
-                                  --jq '.[].url' | grep -v ${{ env.NEW_REPORT_URL }}); do
-            gh issue comment ${{ env.NEW_REPORT_URL }} --body "⬅️ [Previous report]($issue_url)"
-          done
+                                  --jq '.[].url' \
+                                  | grep -v ${{ env.NEW_REPORT_URL }} | head -1)
+
+          gh issue comment ${{ env.NEW_REPORT_URL }} --body "⬅️ [Previous report]($previous_report_url)"
 
           # Link to the newer report from any older report that is still open,
           # then close the older report.

.github/workflows/check-for-spammy-issues.yml

@@ -23,7 +23,7 @@ jobs:
             const repo = 'docs'
 
             const titleWordCount = issue.title.trim().split(' ').length
-            const titleWordCountMin = 2
+            const titleWordCountMin = 3
 
             try {
               await github.teams.getMembershipForUserInOrg({
@@ -35,18 +35,18 @@ jobs:
               // Do not perform this workflow with GitHub employees. This return
               // statement only gets hit if the user is a GitHub employee
               return
-            } catch(err) {
+            } catch (err) {
               // An error will be thrown if the user is not a GitHub employee
               // If a user is not a GitHub employee, we should check to see if title has at least the minimum required number of words in it and if it does, we can exit the workflow
 
-              if(titleWordCount > titleWordCountMin) {
+              if (titleWordCount >= titleWordCountMin) {
                 return
               }
             }
 
             //
             // Assuming the user is not a GitHub employee and the issue title
-            // has the minimum number of words required, proceed.
+            // does not contain the minimum number of words required, proceed.
             //
 
             // Close the issue and add the invalid label
@@ -63,7 +63,7 @@ jobs:
               owner: owner,
               repo: repo,
               issue_number: issue.number,
-              body: "This issue appears to have been opened accidentally. I'm going to close it now, but feel free to open a new issue or ask any questions in [discussions](https://github.com/github/docs/discussions)!"
+              body: `This issue may have been opened accidentally. I'm going to close it now, but feel free to open a new issue with a more descriptive title or ask any questions in [discussions](https://github.com/github/docs/discussions)!`
             });
 
             // Add the issue to the Done column on the triage board

.github/workflows/content-changes-table-comment.yml

@@ -0,0 +1,123 @@
+name: Content Changes Table Comment
+
+# **What it does**: When a PR is opened in docs-internal or docs, it adds the staging preview and live article links in a Content Directory Changes table in a comment
+# **Why we have it**: To help Docs Content team members and contributors automatically have their staging/live article links added to the table
+# **Who does it impact**: docs-internal/docs maintainers and contributors
+
+on:
+  workflow_dispatch:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  PR-Preview-Links:
+    name: Add staging/live links to PR
+    runs-on: ubuntu-latest
+    outputs:
+      filterContentDir: ${{ steps.filter.outputs.filterContentDir }}
+    steps:
+      - name: Get files changed
+        uses: dorny/paths-filter@eb75a1edc117d3756a18ef89958ee59f9500ba58
+        id: filter
+        with:
+          # Base branch used to get changed files
+          base: ${{ github.event.pull_request.base.ref }}
+
+          # Enables setting an output in the format in `${FILTER_NAME}_files
+          # with the names of the matching files formatted as JSON array
+          list-files: json
+
+          # Returns list of changed files matching each filter
+          filters: |
+            filterContentDir:
+              - 'content/**/*'
+  filterContentDir:
+    needs: PR-Preview-Links
+    if: ${{ needs.PR-Preview-Links.outputs.filterContentDir == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: check out repo content
+        uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
+
+      - name: Setup Node
+        uses: actions/setup-node@38d90ce44d5275ad62cc48384b3d8a58c500bb5f
+        with:
+          node-version: 16.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Get changes table
+        uses: actions/github-script@2b34a689ec86a68d8ab9478298f91d5401337b7d
+        id: changes
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          script: |
+            const slugify = require('github-slugger').slug
+
+            const HEROKU_APPNAME_MAX_LENGTH = 30
+
+            const repoName = context.payload.repository.name
+            const branchName = context.payload.pull_request.head.ref
+            const prNumber = context.payload.number
+            const stagingPrefix = getStagingPrefix(repoName, prNumber, branchName)
+
+            const response = await github.repos.compareCommits({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              base: context.payload.pull_request.base.sha,
+              head: context.payload.pull_request.head.sha
+            })
+
+            let changedFiles = response.data.files
+              .map(e => e.filename)
+              .filter(file => file.startsWith('content/') && !file.includes('index'))
+
+            let markdownTable = '| **Article in Staging** | **Live Article** | **Source** | **Changes** |\n| ----------- | ----------- | ----------- | ----------- |\n'
+            for (let file of changedFiles) {
+              file = file.split('content')[1]
+              const fileURL = file.substring(0, file.length-3)
+              const stagingLink = `https://${stagingPrefix}.herokuapp.com${fileURL}`
+              let fileTitle = file.split('/').pop()
+              fileTitle = fileTitle.substring(0, fileTitle.length - 3)
+              const markdownLine = '| [' + fileTitle + '](' + stagingLink + ') | [' + fileTitle + '](https://docs.github.com' + fileURL + ') | | |\n' 
+              markdownTable += markdownLine
+            }
+
+            function getStagingPrefix (prefix, prNumber, branch) {
+              // Added a - in front of prNumber
+              return `${prefix}-${prNumber}--${slugify(branch)}`
+                .toLowerCase()
+                .slice(0, HEROKU_APPNAME_MAX_LENGTH)
+                .replace(/_/g, '-')
+                .replace(/-+$/, '')
+            }
+            core.setOutput('changesTable', markdownTable)
+
+      - name: Find content directory changes comment
+        uses: peter-evans/find-comment@0da1f4fc1f20cd898368bd56089d391df418f52f
+        id: findComment
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: '## ⚠️ Automatically generated comment ⚠️'
+
+      - name: Update comment
+        uses: peter-evans/create-or-update-comment@5221bf4aa615e5c6e95bb142f9673a9c791be2cd
+        with:
+          comment-id: ${{ steps.findComment.outputs.comment-id }}
+          issue-number: ${{ github.event.pull_request.number }}
+          body: |
+            ## ⚠️ Automatically generated comment ⚠️ 
+            **This comment is automatically generated and will be overwritten the every time changes are committed to this branch.**
+
+            The table contains an overview of files in the `content` directory that have been changed in this pull request. It's provided to make it easy to review your changes on the staging site. Please note that changes to the `data` directory will not show up in this table.
+
+            ---
+
+            ### Content directory changes
+            _You may find it useful to copy this table into the pull request summary. There you can edit it to share links to important articles or changes and to give a high-level overview of how the changes in your pull request support the overall goals of the pull request._
+            ${{ steps.changes.outputs.changesTable }}
+          edit-mode: replace

.github/workflows/merged-notification.yml

@@ -11,7 +11,7 @@ on:
 
 jobs:
   comment:
-    if: github.repository == 'github/docs' && github.event.pull_request.merged && github.event.pull_request.base.ref == github.event.repository.default_branch
+    if: github.repository == 'github/docs' && github.event.pull_request.merged && github.event.pull_request.base.ref == github.event.repository.default_branch && github.event.pull_request.user.login != 'Octomerger'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/github-script@2b34a689ec86a68d8ab9478298f91d5401337b7d

.github/workflows/openapi-schema-check.yml

@@ -1,8 +1,16 @@
 name: OpenAPI dev mode check
 
-# **What it does**:
-# **Why we have it**:
-# **Who does it impact**:
+# **What it does**: Checks that the files in lib/rest/static/decorated match
+#   the files in lib/rest/static/dereferenced. Checks that the decorated
+#   schemas in lib/rest/static/decorated are not in development mode.
+#   Development mode schemas have a branch name and development mode tag in the
+#   info.version property.
+# **Why we have it**: To ensure that we aren't every shipping decorated schemas
+#   that are out of sync with the source derefereced schema. To ensure that
+#   decorated schemas generated locally are not published. Locally generated
+#   decorated schemas are pushing up to the remote for staging purposes only.
+# **Who does it impact**: Docs content writers updating REST API docs and
+#   the docs engineering team as maintainers of the scripts and workflows.
 
 on:
   workflow_dispatch:
@@ -12,6 +20,8 @@ on:
   pull_request:
     paths:
       - 'lib/rest/static/**'
+      - 'script/rest/**/*.js'
+      - 'package*.json'
 
 jobs:
   check-schema-versions:

.github/workflows/staging-build-pr.yml

@@ -0,0 +1,89 @@
+name: Staging - Build PR
+
+# **What it does**: Builds PRs before deploying them.
+# **Why we have it**: Because it's not safe to share our deploy secrets with forked repos: https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
+# **Who does it impact**: All contributors.
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - unlocked
+
+jobs:
+  build:
+    if: ${{ github.repository == 'github/docs-internal' || github.repository == 'github/docs' }}
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    concurrency:
+      group: staging_${{ github.head_ref }}
+      cancel-in-progress: true
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
+
+      - name: Setup node
+        uses: actions/setup-node@38d90ce44d5275ad62cc48384b3d8a58c500bb5f
+        with:
+          node-version: 16.x
+          cache: npm
+
+      # Required for `npm pkg ...` command support
+      - name: Update to npm@^7.20.0
+        run: npm install --global npm@^7.20.0
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Remove development-only dependencies
+        run: npm prune --production
+
+      - name: Remove all npm scripts
+        run: npm pkg delete scripts
+
+      - name: Set npm script for Heroku build to noop
+        run: npm set-script heroku-postbuild "echo 'Application was pre-built!'"
+
+      - name: Create an archive
+        run: |
+          tar -cf app.tar \
+            node_modules/ \
+            .next/ \
+            assets/ \
+            content/ \
+            data/ \
+            includes/ \
+            lib/ \
+            middleware/ \
+            translations/ \
+            server.mjs \
+            package*.json \
+            .npmrc \
+            feature-flags.json \
+            next.config.js \
+            app.json \
+            Procfile
+
+      # Upload only the files needed to run this application.
+      # We are not willing to trust the rest (e.g. script/) for the remainder
+      # of the deployment process.
+      - name: Upload build artifact
+        uses: actions/upload-artifact@27121b0bdffd731efa15d66772be8dc71245d074
+        with:
+          name: pr_build
+          path: app.tar
+
+      - name: Send Slack notification if workflow fails
+        uses: someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd
+        if: ${{ failure() }}
+        with:
+          channel: ${{ secrets.DOCS_STAGING_DEPLOYMENT_FAILURES_SLACK_CHANNEL_ID }}
+          bot-token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+          color: failure
+          text: Staging build failed for PR ${{ github.event.pull_request.html_url }} at commit ${{ github.sha }}. See https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}

.github/workflows/staging-deploy-pr.yml

@@ -5,96 +5,155 @@ name: Staging - Deploy PR
 # **Who does it impact**: All contributors.
 
 on:
-  pull_request:
+  workflow_run:
+    workflows:
+      - 'Staging - Build PR'
     types:
-      - opened
-      - reopened
-      - synchronize
-      - unlocked
-  workflow_dispatch:
-    inputs:
-      pullRequestUrl:
-        description: 'Pull Request URL'
-        required: true
-        default: 'https://github.com/github/docs/pull/1234'
-      forceRebuild:
-        description: 'Force the Heroku App to be rebuilt from scratch? (true/false)'
-        required: false
-        default: 'false'
+      - completed
+
+env:
+  EARLY_ACCESS_SCRIPT_PATH: script/early-access/clone-for-build.js
+  EARLY_ACCESS_SUPPORT_FILES: script/package.json
+  # In this specific workflow relationship, the `github.event.workflow_run.pull_requests`
+  # array will always contain only 1 item! Specifically, it will contain the PR associated
+  # with the `github.event.workflow_run.head_branch` that triggered the preceding
+  # `pull_request` event that triggered the "Staging - Build PR" workflow.
+  PR_URL: ${{ github.event.workflow_run.repository.html_url }}/pull/${{ github.event.workflow_run.pull_requests[0].number }}
 
 jobs:
-  validate-inputs:
-    if: ${{ github.repository == 'github/docs-internal' || github.repository == 'github/docs' }}
-    name: Validate inputs
+  prepare:
+    if: |
+      ${{
+        github.event.workflow_run.conclusion == 'success' &&
+        (github.repository == 'github/docs-internal' || github.repository == 'github/docs')
+      }}
     runs-on: ubuntu-latest
-    timeout-minutes: 2
+    timeout-minutes: 5
+    concurrency:
+      group: staging_${{ github.event.workflow_run.head_branch }}
+      cancel-in-progress: true
     outputs:
-      headRef: ${{ steps.validate.outputs.headRef }}
+      source_blob_url: ${{ steps.build-source.outputs.download_url }}
     steps:
-      - if: ${{ github.event_name == 'workflow_dispatch' }}
-        name: Check out repo
-        uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
-        with:
-          # Enables cloning the Early Access repo later with the relevant PAT
-          persist-credentials: 'false'
+      - name: Dump event context
+        env:
+          GITHUB_EVENT_CONTEXT: ${{ toJSON(github.event) }}
+        run: echo "$GITHUB_EVENT_CONTEXT"
 
-      - if: ${{ github.event_name == 'workflow_dispatch' }}
-        name: Setup node
+      - name: Download build artifact
+        uses: dawidd6/action-download-artifact@b9571484721e8187f1fd08147b497129f8972c74
+        with:
+          workflow: ${{ github.event.workflow_run.workflow_id }}
+          run_id: ${{ github.event.workflow_run.id }}
+          name: pr_build
+          path: ./
+
+      - name: Show contents
+        run: ls -l
+
+      - name: Extract the archive
+        run: |
+          tar -xf app.tar -C ./
+          rm app.tar
+
+      - name: Show contents again
+        run: ls -l
+
+      - if: ${{ github.repository == 'github/docs-internal' }}
+        name: Setup node to clone early access
         uses: actions/setup-node@38d90ce44d5275ad62cc48384b3d8a58c500bb5f
         with:
           node-version: 16.x
           cache: npm
 
-      - if: ${{ github.event_name == 'workflow_dispatch' }}
-        name: Install dependencies
-        run: npm ci
+      - if: ${{ github.repository == 'github/docs-internal' }}
+        name: Download the script to clone early access
+        uses: Bhacaz/checkout-files@c8f01756bfd894ba746d5bf48205e19000b0742b
+        with:
+          files: ${{ env.EARLY_ACCESS_SCRIPT_PATH }} ${{ env.EARLY_ACCESS_SUPPORT_FILES }}
+          token: ${{ secrets.GITHUB_TOKEN }}
 
-      - if: ${{ github.event_name == 'workflow_dispatch' }}
-        name: Validate and get head.ref
-        id: validate
+      # Add any dependencies that are needed for this workflow below
+      - if: ${{ github.repository == 'github/docs-internal' }}
+        name: Install temporary development-only dependencies
+        run: npm install --no-save rimraf
+
+      - if: ${{ github.repository == 'github/docs-internal' }}
+        name: Clone early access
+        run: node ${{ env.EARLY_ACCESS_SCRIPT_PATH }}
+        env:
+          DOCUBOT_REPO_PAT: ${{ secrets.DOCUBOT_REPO_PAT }}
+          GIT_BRANCH: ${{ github.event.workflow_run.head_branch }}
+
+      # Remove any dependencies installed for this workflow below
+      - if: ${{ github.repository == 'github/docs-internal' }}
+        name: Remove development-only dependencies
+        run: npm prune --production
+
+      - if: ${{ github.repository == 'github/docs-internal' }}
+        name: Delete the script directory after cloning early access
+        run: rm -rf script/
+
+      - name: Create a gzipped archive
+        run: |
+          touch app.tar.gz
+          tar --exclude=app.tar.gz -czf app.tar.gz ./
+
+      - name: Install Heroku client development-only dependency
+        run: npm install --no-save heroku-client
+
+      - name: Create a Heroku build source
+        id: build-source
         uses: actions/github-script@2b34a689ec86a68d8ab9478298f91d5401337b7d
         env:
-          PR_URL: ${{ github.event.inputs.pullRequestUrl }}
-          FORCE_REBUILD: ${{ github.event.inputs.forceRebuild }}
+          HEROKU_API_TOKEN: ${{ secrets.HEROKU_API_TOKEN }}
         with:
           script: |
-            const parsePrUrl = require('./script/deployment/parse-pr-url')
+            const { owner, repo } = context.repo
 
-            // Manually resolve workflow_dispatch inputs
-            const { PR_URL, FORCE_REBUILD } = process.env
-
-            if (!['true', 'false'].includes(FORCE_REBUILD)) {
-              throw new Error(`'forceRebuild' input must be either 'true' or 'false' but was '${FORCE_REBUILD}'`)
+            if (owner !== 'github') {
+              throw new Error(`Repository owner must be 'github' but was: ${owner}`)
+            }
+            if (repo !== 'docs-internal' && repo !== 'docs') {
+              throw new Error(`Repository name must be either 'docs-internal' or 'docs' but was: ${repo}`)
             }
 
-            const { owner, repo, pullNumber } = parsePrUrl(PR_URL)
-            if (!owner || !repo || !pullNumber) {
-              throw new Error(`'pullRequestUrl' input must match URL format 'https://github.com/github/(docs|docs-internal)/pull/123' but was '${PR_URL}'`)
-            }
+            const Heroku = require('heroku-client')
+            const heroku = new Heroku({ token: process.env.HEROKU_API_TOKEN })
 
-            const { data: pullRequest } = await github.pulls.get({
-              owner,
-              repo,
-              pull_number: pullNumber
-            })
+            const { source_blob: sourceBlob } = await heroku.post('/sources')
+            const { put_url: uploadUrl, get_url: downloadUrl } = sourceBlob
 
-            core.setOutput('headRef', pullRequest.head.ref)
+            core.setOutput('upload_url', uploadUrl)
+            core.setOutput('download_url', downloadUrl)
+
+      # See: https://devcenter.heroku.com/articles/build-and-release-using-the-api#sources-endpoint
+      - name: Upload to the Heroku build source
+        run: |
+          curl '${{ steps.build-source.outputs.upload_url }}' \
+            -X PUT \
+            -H 'Content-Type:' \
+            --data-binary @app.tar.gz
+
+      - name: Send Slack notification if workflow fails
+        uses: someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd
+        if: ${{ failure() }}
+        with:
+          channel: ${{ secrets.DOCS_STAGING_DEPLOYMENT_FAILURES_SLACK_CHANNEL_ID }}
+          bot-token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+          color: failure
+          text: Staging preparation failed for PR ${{ env.PR_URL }} at commit ${{ github.sha }}. See https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}
 
   deploy:
-    if: ${{ github.repository == 'github/docs-internal' || github.repository == 'github/docs' }}
-    needs: validate-inputs
-    name: Deploy
+    needs: prepare
     runs-on: ubuntu-latest
     timeout-minutes: 10
     concurrency:
-      group: staging_${{ needs.validate-inputs.outputs.headRef || github.head_ref }}
+      group: staging_${{ github.event.workflow_run.head_branch }}
       cancel-in-progress: true
     steps:
-      - name: Check out repo
+      - name: Check out repo's default branch
         uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
-        with:
-          # Enables cloning the Early Access repo later with the relevant PAT
-          persist-credentials: 'false'
 
       - name: Setup node
         uses: actions/setup-node@38d90ce44d5275ad62cc48384b3d8a58c500bb5f
@@ -105,16 +164,19 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Install one-off development-only dependencies
+        run: npm install --no-save --include=optional esm
+
       - name: Deploy
+        id: deploy
         uses: actions/github-script@2b34a689ec86a68d8ab9478298f91d5401337b7d
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           HEROKU_API_TOKEN: ${{ secrets.HEROKU_API_TOKEN }}
-          DOCUBOT_REPO_PAT: ${{ secrets.DOCUBOT_REPO_PAT }}
           HYDRO_ENDPOINT: ${{ secrets.HYDRO_ENDPOINT }}
           HYDRO_SECRET: ${{ secrets.HYDRO_SECRET }}
-          PR_URL: ${{ github.event.inputs.pullRequestUrl }}
-          FORCE_REBUILD: ${{ github.event.inputs.forceRebuild }}
+          PR_URL: ${{ env.PR_URL }}
+          SOURCE_BLOB_URL: ${{ needs.prepare.outputs.source_blob_url }}
         with:
           script: |
             const { GITHUB_TOKEN, HEROKU_API_TOKEN } = process.env
@@ -129,9 +191,13 @@ jobs:
               throw new Error('You must supply a HEROKU_API_TOKEN environment variable!')
             }
 
-            const parsePrUrl = require('./script/deployment/parse-pr-url')
-            const getOctokit = require('./script/helpers/github')
-            const deployToStaging = require('./script/deployment/deploy-to-staging')
+            // Workaround to allow us to load ESM files with `require(...)`
+            const esm = require('esm')
+            require = esm({})
+
+            const { default: parsePrUrl } = require('./script/deployment/parse-pr-url')
+            const { default: getOctokit } = require('./script/helpers/github')
+            const { default: deployToStaging } = require('./script/deployment/deploy-to-staging')
 
             // This helper uses the `GITHUB_TOKEN` implicitly!
             // We're using our usual version of Octokit vs. the provided `github`
@@ -139,33 +205,24 @@ jobs:
             const octokit = getOctokit()
 
             try {
-              let pullRequest = null
-              let forceRebuild = false
-
-              // Manually resolve workflow_dispatch inputs
-              if (context.eventName === 'workflow_dispatch') {
-                const { PR_URL, FORCE_REBUILD } = process.env
-
-                forceRebuild = FORCE_REBUILD === 'true'
-
-                const { owner, repo, pullNumber } = parsePrUrl(PR_URL)
-                if (!owner || !repo || !pullNumber) {
-                  throw new Error(`'pullRequestUrl' input must match URL format 'https://github.com/github/(docs|docs-internal)/pull/123' but was '${PR_URL}'`)
-                }
-
-                const { data: pr } = await octokit.pulls.get({
-                  owner,
-                  repo,
-                  pull_number: pullNumber
-                })
-                pullRequest = pr
+              const { PR_URL, SOURCE_BLOB_URL } = process.env
+              const { owner, repo, pullNumber } = parsePrUrl(PR_URL)
+              if (!owner || !repo || !pullNumber) {
+                throw new Error(`'pullRequestUrl' input must match URL format 'https://github.com/github/(docs|docs-internal)/pull/123' but was '${PR_URL}'`)
               }
 
+              const { data: pullRequest } = await octokit.pulls.get({
+                owner,
+                repo,
+                pull_number: pullNumber
+              })
+
               await deployToStaging({
-                herokuToken: HEROKU_API_TOKEN,
                 octokit,
-                pullRequest: pullRequest || context.payload.pull_request,
-                forceRebuild,
+                pullRequest,
+                forceRebuild: false,
+                // These parameters will ONLY be set by Actions
+                sourceBlobUrl: SOURCE_BLOB_URL,
                 runId: context.runId
               })
             } catch (error) {
@@ -173,3 +230,21 @@ jobs:
               console.error(error)
               throw error
             }
+
+      - name: Mark the deployment as inactive if timed out
+        if: ${{ steps.deploy.outcome == 'cancelled' }}
+        uses: actions/github-script@2b34a689ec86a68d8ab9478298f91d5401337b7d
+        with:
+          script: |
+            // TODO: Find the relevant deployment
+            // TODO: Create a new deployment status for it as "inactive"
+            return 'TODO'
+
+      - name: Send Slack notification if workflow fails
+        uses: someimportantcompany/github-actions-slack-message@0b470c14b39da4260ed9e3f9a4f1298a74ccdefd
+        if: ${{ failure() }}
+        with:
+          channel: ${{ secrets.DOCS_STAGING_DEPLOYMENT_FAILURES_SLACK_CHANNEL_ID }}
+          bot-token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
+          color: failure
+          text: Staging deployment failed for PR ${{ env.PR_URL }} at commit ${{ github.sha }}. See https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}

.github/workflows/staging-undeploy-pr.yml

@@ -5,7 +5,7 @@ name: Staging - Undeploy PR
 # **Who does it impact**: All contributors.
 
 on:
-  pull_request:
+  pull_request_target:
     types:
       - closed
       - locked
@@ -20,10 +20,10 @@ jobs:
       group: staging_${{ github.head_ref }}
       cancel-in-progress: true
     steps:
-      - name: Check out repo
+      - name: Check out repo's default branch
         uses: actions/checkout@5a4ac9002d0be2fb38bd78e4b4dbde5606d7042f
         with:
-          # Enables cloning the Early Access repo later with the relevant PAT
+          # For enhanced security: https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
           persist-credentials: 'false'
 
       - name: Setup node
@@ -35,6 +35,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Install one-off development-only dependencies
+        run: npm install --no-save --include=optional esm
+
       - name: Undeploy
         uses: actions/github-script@2b34a689ec86a68d8ab9478298f91d5401337b7d
         env:
@@ -54,8 +57,12 @@ jobs:
               throw new Error('You must supply a HEROKU_API_TOKEN environment variable!')
             }
 
-            const getOctokit = require('./script/helpers/github')
-            const undeployFromStaging = require('./script/deployment/undeploy-from-staging')
+            // Workaround to allow us to load ESM files with `require(...)`
+            const esm = require('esm')
+            require = esm({})
+
+            const { default: getOctokit } = require('./script/helpers/github')
+            const { default: undeployFromStaging } = require('./script/deployment/undeploy-from-staging')
 
             // This helper uses the `GITHUB_TOKEN` implicitly!
             // We're using our usual version of Octokit vs. the provided `github`
@@ -64,7 +71,6 @@ jobs:
 
             try {
               await undeployFromStaging({
-                herokuToken: HEROKU_API_TOKEN,
                 octokit,
                 pullRequest: context.payload.pull_request,
                 runId: context.runId

.github/workflows/workflow-lint.yml

@@ -28,4 +28,4 @@ jobs:
       - name: Run linter
         uses: cschleiden/actions-linter@caffd707beda4fc6083926a3dff48444bc7c24aa
         with:
-          workflows: '[".github/workflows/*.yml", ".github/workflows/*.yaml", "!.github/workflows/remove-from-fr-board.yaml"]'
+          workflows: '[".github/workflows/*.yml", ".github/workflows/*.yaml", "!.github/workflows/remove-from-fr-board.yaml", "!.github/workflows/staging-deploy-pr.yml"]'

.gitignore

@@ -10,7 +10,6 @@ coverage/
 /data/early-access
 .next
 .eslintcache
-/storybook/
 
 # blc: broken link checker
 blc_output.log

.storybook/main.js

@@ -1,9 +0,0 @@
-const path = require('path')
-
-module.exports = {
-  stories: [
-    '../components/stories/**/*.stories.mdx',
-    '../components/stories/**/*.stories.@(js|jsx|ts|tsx)',
-  ],
-  addons: ['@storybook/addon-links', '@storybook/addon-essentials', '@storybook/preset-scss'],
-}

.storybook/preview.js

@@ -1,11 +0,0 @@
-import '../stylesheets/index.scss'
-
-export const parameters = {
-  actions: { argTypesRegex: '^on[A-Z].*' },
-  controls: {
-    matchers: {
-      color: /(background|color)$/i,
-      date: /Date$/,
-    },
-  },
-}

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-## Introduction
+## Welcome to GitHub docs contributing guide
 
 Thank you for investing your time in contributing to our project. Any contribution you make would reflect in the [docs.github.com](https://docs.github.com/en) page :sparkles:. 
 
@@ -8,11 +8,11 @@ In this guide you will get an overview of the contribution workflow from opening
 
 <!-- Use [CodeTour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) a VScode extension playback walkthroughs of how to get started with. Depends on this issue https://github.com/github/docs-team/issues/800  -->
 
-**Table of Contents**
+**Table of contents**
 
 Use table of contents icon <img src="./assets/images/table-of-contents.png" width="25" height="25" /> on the top left corner of the this document to get to a specific section of this guide quickly.
 
-## New Contributor Guide
+## New contributor guide
 
   See [README.md](README.md) to get an overview of the project. Here are some helpful resources to get you comfortable with open source contribution. 
 
@@ -65,7 +65,9 @@ Forking repository
 Install/Update your to **Node.js v16**. For more information, see "[contributing/development.md](contributing/development.md)."
 
 Create a working branch and start with your changes!
+
 ### Commit your update:
+
 Commit the changes once you are happy with them. Here are some commonly used short and fun commit messages.
 
   - :pencil2: `:pencil2:` fix typos
@@ -75,6 +77,7 @@ Commit the changes once you are happy with them. Here are some commonly used sho
  (Cant think of more, any ideas?)
 
 Once you are ready with your changes, don't forget to [self review](/contributing/self-review.md), to quicken the review process :zap:.
+
 ### Pull Request
 
 - When you're done making the changes, open a PR (pull request). 
@@ -84,17 +87,16 @@ Once you are ready with your changes, don't forget to [self review](/contributin
 - Enable the checkbox to [allow maintainer edits](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so the branch can be updated for a merge.
 - Once you submit your PR, one of the writers would review your proposal. Keep an eye for any questions or request for additional information.
 - We may ask for changes to be made before a PR can be merged, either using [suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
-
 - As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations).
-- After that, we may have questions, check back on your PR to keep up with the conversation.
 - If you run into any merge issues, checkout this [git tutorial](https://lab.github.com/githubtraining/managing-merge-conflicts) to help you resolve merge conflicts and other issues.
 
 ### Your PR is merged!
+
 Congratulations :tada::tada: The whole GitHub community thanks you :sparkles:. 
 
 Once your PR is merged, you will be proudly listed as a contributor in the [contributor chart](https://github.com/github/docs/graphs/contributors). 
 
-Now that you are part of the GitHub docs community, see what other ways you [contribute to the docs](/contributing/types-of-contributions.md).
+Now that you are part of the GitHub docs community, see how else you can [contribute to the docs](/contributing/types-of-contributions.md).
 
 ## Windows
 
@@ -106,4 +108,4 @@ This site can be developed on Windows, however a few potential gotchas need to b
 1. Filename too long error: There is a 260 character limit for a filename when Git is compiled with `msys`. While the suggestions below are not guaranteed to work and could possibly cause other issues, a few workarounds include:
     - Shorten the path by cloning this repo directly into `C:\`
     - Use a different Git client on Windows
-    - Update Git configuration: `git config --system core.longpaths true`
+    - Update Git configuration: `git config --system core.longpaths true`

Dockerfile

@@ -18,6 +18,7 @@ WORKDIR /usr/src/docs
 FROM base as all_deps
 
 COPY package*.json ./
+COPY .npmrc ./
 
 RUN npm ci
 
@@ -48,7 +49,6 @@ COPY content/index.md ./content/index.md
 COPY next.config.js ./next.config.js
 COPY tsconfig.json ./tsconfig.json
 COPY next-env.d.ts ./next-env.d.ts
-COPY .storybook ./.storybook
 
 RUN npx tsc --noEmit
 

README.md

@@ -14,13 +14,13 @@ See our [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions of how to g
 
 We accept different [types of contributions](CONTRIBUTING.md/#types-of-contributions-memo), including some that don't require you to write a single line of code.
 
-For quick fixes like typos, updates, link fixes etc., use **make a contribution** to make changes and submit a PR.
+On the GitHub Docs site, you can click **make a contribution** to open a PR for quick fixes like typos, updates, or link fixes.
 
 <img src="./assets/images/contribution_cta.png" width="400">
 
-**Open an issue** using an [issue template](https://github.com/github/docs/issues/new/choose).
+For more complex contribution, you can **open an issue** using an [issue template](https://github.com/github/docs/issues/new/choose) to describe the changes you'd like to see.
 
-**Solve an issue** by first scanning through our [existing issues](https://github.com/github/docs/issues). When ready, check out [Getting Started with Contributing](/CONTRIBUTING.md) for detailed instructions.
+If you're looking for a way to contribute, you can scan through our [existing issues](https://github.com/github/docs/issues) for something to work on. When ready, check out [Getting Started with Contributing](/CONTRIBUTING.md) for detailed instructions.
 
 ### Join us in discussions
 
@@ -32,8 +32,6 @@ If you're having trouble with your GitHub account, contact [Support](https://sup
 
 That's how you can easily become a member of the GitHub Documentation community. :sparkles:
 
-If you want to know more, or you're making a more complex contribution, check out [CONTRIBUTING.md](/CONTRIBUTING.md).
-
 ## READMEs
 
 In addition to the README you're reading right now, this repo includes other READMEs that describe the purpose of each subdirectory in more detail: