Tighten code comments in .github/workflows e-l (#63428) · mogya/github_docs@26f9096 · GitHub
Skip to content

Commit 26f9096

Browse files
heiskrCopilot
heiskr
and
Copilot
authored
Tighten code comments in .github/workflows e-l (#63428)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7c52b57f-2c29-4aa1-8233-99d0d6e13571
1 parent 3e53da2 commit 26f9096

20 files changed

Lines changed: 113 additions & 249 deletions

‎.github/workflows/enterprise-dates.yml‎

Lines changed: 6 additions & 10 deletions

‎.github/workflows/enterprise-release-issue.yml‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
11
name: Open Enterprise release or deprecation issue
22

3-
# **What it does**: Checks if there is an Enterprise release or deprecation upcoming, and if so, opens an issue with the tasks to be completed.
4-
# **Why we have it**: GHES releases and deprecations run on a predictable schedule, so we can automate some of the project management aspects.
5-
# **Who does it impact**: Docs engineering, docs content.
3+
# GHES releases and deprecations follow a predictable schedule, so this workflow opens
4+
# their planning issues automatically.
65

76
on:
87
workflow_dispatch:
98
schedule:
10-
- cron: '20 16 * * 1' # Run every Monday at 16:20 UTC / 8:20 PST
9+
- cron: '20 16 * * 1'
1110

1211
permissions:
1312
contents: read

‎.github/workflows/expertise-required-label-message.yml‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
name: Expertise Required label message
22

3-
# **What it does**: Adds a bot comment stating a certain level of expertise is required to a docs-content issue when the `contributor-expertise-required` label is applied
4-
# **Why we have it**: We need a method to surface a message denoting if an issue requires a certain level of expertise in order to be resolved
5-
# **Who does it impact**: Open Source and Hubbers
3+
# Surface contributor expertise requirements directly on labeled github/docs issues.
64

75
on:
86
issues:

‎.github/workflows/feedback-prompt.yml‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,8 @@ permissions:
1010

1111
jobs:
1212
comment-on-pr:
13-
# This workflow should only run on the 'github/docs-internal' repository because it posts a feedback request
14-
# to non-Docs team contributors when their PR is merged into the main branch.
15-
# The feedback request asks contributors to leave feedback on their contributing experience in Slack.
13+
# Ask merged main-branch pull request authors for feedback when they are outside
14+
# the docs-content team.
1615
if: github.repository == 'github/docs-internal' && github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'main'
1716

1817
runs-on: ubuntu-latest
@@ -26,16 +25,13 @@ jobs:
2625
script: |
2726
try {
2827
const pr = context.payload.pull_request;
29-
// Team is addressed by numeric ID (org github = 9919, team docs-content = 2796154)
30-
// because IDs survive team renames and slugs do not.
28+
// Numeric IDs survive team renames; slugs do not. GitHub org 9919, docs-content team 2796154.
3129
await github.request('GET /organizations/{org_id}/team/{team_id}/memberships/{username}', {
3230
org_id: 9919,
3331
team_id: 2796154,
3432
username: pr.user.login,
3533
});
36-
// Author is in the team. Do nothing!
3734
} catch(err) {
38-
// Author not in team
3935
core.exportVariable('NON_DOCS_HUBBER', 'true');
4036
}
4137
@@ -66,7 +62,6 @@ jobs:
6662
" - Thanks for your contribution! " +
6763
"If you think something could be improved about the contributor experience, please post in `#docs-contributor-feedback` on Slack.";
6864
} else {
69-
// nobody to mention!
7065
commentBody =
7166
"👋 Thanks for your contribution! " +
7267
"If you think something could be improved about the contributor experience, please post in `#docs-contributor-feedback` on Slack.";

‎.github/workflows/first-responder-v2-prs-collect.yml‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
name: Add maintenance PRs to the docs-content FR project v2
22

3-
# **What it does**: Adds docs-internal pull requests authored by docs-bot to the docs-content FR project v2
4-
# **Why we have it**: So we don't lose track of maintenance pull requests for docs-content to review
5-
# **Who does it impact**: Docs content
3+
# The docs-content FR project is the review queue for docs-bot maintenance pull requests.
64

75
on:
86
pull_request:
@@ -25,10 +23,6 @@ jobs:
2523
steps:
2624
- name: Checkout repository
2725
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
28-
29-
# Add to the FR project
30-
# and set type to "Maintenance"
31-
# and set date to now
3226
- name: Triage to docs-content FR project
3327
env:
3428
GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}

‎.github/workflows/generate-code-scanning-query-lists.yml‎

Lines changed: 12 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,7 @@
11
name: Generate code scanning query lists
22

3-
# **What it does**: This workflow is currently run manually approximately every two weeks as part
4-
# of the release process for the CodeQL CLI. We hope to automate this in the future
5-
# When run, this workflow generates updated query lists with data from the codeql
6-
# repository, and creates a pull request if there are updates.
7-
# **Why we have it**: So we can automate CodeQL query tables and show code scanning users the built in queries.
8-
# **Who does it impact**: Anyone making CodeQL query suite changes in `github/codeql`, and wanting to get them published on the docs site.
3+
# Manual CodeQL CLI release runs, about every two weeks, generate query table reusables
4+
# from github/codeql and open a pull request when they change.
95

106
on:
117
workflow_dispatch:
@@ -53,16 +49,14 @@ jobs:
5349
echo "Copied files from github/codeql repo. Commit SHA: $OPENAPI_COMMIT_SHA"
5450
5551
- name: Download CodeQL CLI
56-
# Look under the `codeql` directory, as this is where we checked out the `github/codeql` repo
52+
# fetch-codeql lives in the checked-out github/codeql repository.
5753
uses: ./codeql/.github/actions/fetch-codeql
5854

5955
- name: Test CodeQL CLI Download
6056
shell: bash
6157
run: codeql --version
6258

63-
# "Server for running multiple commands while avoiding repeated JVM initialization."
64-
# Having started this should speed up the execution of the various
65-
# CLI calls of the executable.
59+
# Start the CodeQL CLI server once so later CodeQL commands avoid repeated JVM initialization.
6660
- name: Start CodeQL CLI server in the background
6761
shell: bash
6862
run: |
@@ -72,10 +66,8 @@ jobs:
7266
7367
- uses: ./.github/actions/install-cocofix
7468
with:
75-
# The Docs Engineering Bot app cannot read the org-scoped
76-
# @github/cocofix package (its Packages permission is repo-level
77-
# only), so this step keeps using the PAT until the app is granted
78-
# organization package read access.
69+
# The Docs Engineering Bot app has repo-level Packages permission and cannot
70+
# read org-scoped packages, so cocofix installation requires the PAT.
7971
token: ${{ secrets.DOCS_BOT_PAT_BASE }}
8072

8173
- name: Build code scanning security query lists
@@ -123,16 +115,14 @@ jobs:
123115
echo "Copied files from github/codeql repo. Commit SHA: $OPENAPI_COMMIT_SHA"
124116
125117
- name: Download CodeQL CLI
126-
# Look under the `codeql` directory, as this is where we checked out the `github/codeql` repo
118+
# fetch-codeql lives in the checked-out github/codeql repository.
127119
uses: ./codeql/.github/actions/fetch-codeql
128120

129121
- name: Test CodeQL CLI Download
130122
shell: bash
131123
run: codeql --version
132124

133-
# "Server for running multiple commands while avoiding repeated JVM initialization."
134-
# Having started this should speed up the execution of the various
135-
# CLI calls of the executable.
125+
# Start the CodeQL CLI server once so later CodeQL commands avoid repeated JVM initialization.
136126
- name: Start CodeQL CLI server in the background
137127
shell: bash
138128
run: |
@@ -210,12 +200,10 @@ jobs:
210200
shell: bash
211201
run: |
212202
213-
# When we started, we downloaded the CodeQL CLI here in this workflow.
214-
# We have no intention of checking that in but we also don't want
215-
# `git status ...` to show it as an untracked file.
203+
# Git status must only report generated query tables, so remove the
204+
# checked-out CodeQL repository.
216205
rm -fr ./codeql
217206
218-
# If nothing to commit, exit now. It's fine. No orphans.
219207
changes=$(git diff --name-only | wc -l)
220208
untracked=$(git status --untracked-files --short | wc -l)
221209
if [[ $changes -eq 0 ]] && [[ $untracked -eq 0 ]]; then
@@ -228,12 +216,10 @@ jobs:
228216
229217
branchname=codeql-query-tables-${{ steps.codeql.outputs.OPENAPI_COMMIT_SHA }}
230218
231-
# Exit if the branch already exists. Since the actions/checkout fetch-depth is 1,
232-
# it doesn't "know" about branches locally, so we need to manually list them.
219+
# Query the remote because actions/checkout with fetch-depth 1 omits other remote-tracking branches.
233220
branchExists=$(git ls-remote --heads origin refs/heads/$branchname | wc -l)
234221
235-
# When run on a pull_request, we're just testing the tooling.
236-
# Exit before it actually pushes the possible changes.
222+
# Pull request runs validate generated files without pushing branches.
237223
if [ "$DRY_RUN" = "true" ]; then
238224
echo "Dry-run mode when run in a pull request"
239225
echo "See the 'Insight into diff' step for the changes it would create PR about."

‎.github/workflows/headless-tests.yml‎

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
name: Headless Tests
22

3-
# **What it does**: This runs our browser tests to test things that depend
4-
# on client-side JavaScript.
5-
# **Why we have it**: Because most automated vitest tests only test static
6-
# input and outputs.
7-
# **Who does it impact**: Docs engineering, open-source engineering contributors.
3+
# Browser tests cover client-side JavaScript behavior that static Vitest tests miss.
84

95
on:
106
workflow_dispatch:
@@ -14,7 +10,7 @@ on:
1410
permissions:
1511
contents: read
1612

17-
# This allows a subsequently queued workflow run to interrupt previous runs
13+
# Cancel older runs for the same ref to save runner time.
1814
concurrency:
1915
group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
2016
cancel-in-progress: true
@@ -27,8 +23,7 @@ jobs:
2723
if: github.repository == 'github/docs-internal' || github.repository == 'github/docs'
2824
runs-on: ubuntu-latest
2925
strategy:
30-
# When we're comfortable a11y tests aren't generating false positives and helping,
31-
# let's remove the matrix and just run playwright in a single job.
26+
# Keep Playwright variants as separate checks while a11y false-positive rates settle.
3227
matrix:
3328
node:
3429
- playwright-rendering
@@ -58,11 +53,9 @@ jobs:
5853
- name: Run Playwright tests
5954
env:
6055
PLAYWRIGHT_WORKERS: ${{ fromJSON('[1, 4]')[github.repository == 'github/docs-internal'] }}
61-
# workaround for https://github.com/nodejs/node/issues/59364 as of 22.18.0
56+
# Supported Node runtimes can hit https://github.com/nodejs/node/issues/59364 without this flag.
6257
NODE_OPTIONS: '--no-experimental-strip-types'
6358
PLAYWRIGHT_TIMEOUT: ${{ matrix.node == 'playwright-a11y' && '60000' || '' }}
6459

65-
# Run playwright rendering tests and a11y tests (axe scans) as distinct checks
66-
# so that we can run them without blocking merges until we can be confident
67-
# results for a11y tests are meaningul and scenarios we're testing are correct.
60+
# Keep a11y scans in a distinct check so branch protection can leave them non-blocking.
6861
run: npm run playwright-test -- ${{ matrix.node }} --reporter list

‎.github/workflows/hubber-contribution-help.yml‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
name: Hubber contribution help
22

3-
# **What it does**: When a PR is opened by a non-Docs team Hubber, adds a bot comment with helpful links
4-
# **Why we have it**: To help non–Docs Hubbers navigate how to get a PR reviewed by the Docs team
5-
# **Who does it impact**: docs-internal contributors
3+
# Help non-Docs Hubbers route content pull requests to the Docs Content review board.
64

75
on:
86
pull_request:
@@ -31,8 +29,7 @@ jobs:
3129
github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
3230
script: |
3331
try {
34-
// Team is addressed by numeric ID (org github = 9919, team docs = 325922)
35-
// because IDs survive team renames and slugs do not.
32+
// Numeric IDs survive team renames; slugs do not. GitHub org 9919, docs team 325922.
3633
await github.request('GET /organizations/{org_id}/team/{team_id}/memberships/{username}', {
3734
org_id: 9919,
3835
team_id: 325922,

‎.github/workflows/index-autocomplete-search.yml‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,11 @@
11
name: Index autocomplete search in Elasticsearch
22

3-
# **What it does**: Indexes AI search autocomplete data into Elasticsearch.
4-
# **Why we have it**: So we can power the APIs for AI search autocomplete.
5-
# **Who does it impact**: docs-engineering
3+
# Keep Elasticsearch autocomplete data current for AI search APIs.
64

75
on:
86
workflow_dispatch:
97
schedule:
10-
- cron: '20 16 * * 1-5' # Run Mon-Fri at 16:20 UTC / 8:20 PST
8+
- cron: '20 16 * * 1-5'
119
pull_request:
1210
paths:
1311
- .github/workflows/index-autocomplete-search.yml

‎.github/workflows/index-general-search-pr.yml‎

Lines changed: 10 additions & 18 deletions

0 commit comments

Comments
 (0)