Skip to content

Commit cf55fc5

Browse files
Trustinbtc999-hueTrustinbtc999-hue
authored
Merge branch 'github:main' into main
2 parents 535e89f + a385982 commit cf55fc5

2,012 files changed

Lines changed: 188847 additions & 50056 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/actions/create-workflow-failure-issue/action.yml‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,11 @@ inputs:
1010
default: github/docs-engineering
1111
required: false
1212

13+
outputs:
14+
issue_url:
15+
description: URL of the created or updated workflow-failure issue (empty if creation failed).
16+
value: ${{ steps.create-new.outputs.issue_url || steps.comment-existing.outputs.issue_url }}
17+
1318
runs:
1419
using: composite
1520
steps:
@@ -31,6 +36,7 @@ runs:
3136
echo "existing_issue=$existing" >> "$GITHUB_OUTPUT"
3237
3338
- name: Comment on existing issue
39+
id: comment-existing
3440
if: steps.check-existing.outputs.existing_issue != ''
3541
shell: bash
3642
env:
@@ -57,8 +63,10 @@ runs:
5763
gh issue comment "$ISSUE_NUMBER" \
5864
--repo "$ISSUE_REPO" \
5965
--body "$body"
66+
echo "issue_url=$GITHUB_SERVER_URL/$ISSUE_REPO/issues/$ISSUE_NUMBER" >> "$GITHUB_OUTPUT"
6067
6168
- name: Create workflow failure issue
69+
id: create-new
6270
if: steps.check-existing.outputs.existing_issue == ''
6371
shell: bash
6472
env:
@@ -86,9 +94,10 @@ runs:
8694
This issue was automatically created by the create-workflow-failure-issue action to enable automated diagnosis.
8795
EOF
8896
)
89-
gh issue create \
97+
url=$(gh issue create \
9098
--repo "$ISSUE_REPO" \
9199
--label "workflow-failure" \
92100
--label "workflow-generated" \
93101
--title "[Workflow Failure] $WORKFLOW_NAME" \
94-
--body "$body"
102+
--body "$body")
103+
echo "issue_url=$url" >> "$GITHUB_OUTPUT"

‎.github/actions/slack-alert/action.yml‎

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,61 @@ inputs:
1010
default: CG5MJHMB2 # docs-alerts
1111
required: false
1212
message:
13-
description: The message to send to Slack
14-
default: The last '${{ github.workflow }}' run failed. See ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
13+
description: >-
14+
Optional message override. When set, it is sent verbatim. When empty (the
15+
default), a standard multi-line failure message is built from the run
16+
context, plus a link to the failure issue if issue_url is provided.
17+
default: ''
18+
required: false
19+
issue_url:
20+
description: >-
21+
Optional link to the tracking failure issue (e.g. the output of the
22+
create-workflow-failure-issue action). Appended to the default message.
23+
Ignored when a custom message is provided.
24+
default: ''
1525
required: false
1626

1727
runs:
1828
using: composite
1929
steps:
30+
# Build the Slack text here so the default message can be multi-line (real
31+
# newlines) and conditionally include the issue link. A caller-supplied
32+
# message is passed through verbatim for backward compatibility.
33+
- name: Build Slack message
34+
id: build
35+
shell: bash
36+
env:
37+
MESSAGE: ${{ inputs.message }}
38+
ISSUE_URL: ${{ inputs.issue_url }}
39+
SOURCE_REPO: ${{ github.repository }}
40+
WORKFLOW_NAME: ${{ github.workflow }}
41+
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
42+
EVENT_NAME: ${{ github.event_name }}
43+
GIT_REF: ${{ github.ref }}
44+
ACTOR: ${{ github.actor }}
45+
run: |
46+
# Escape Slack mrkdwn control chars in interpolated context fields so a
47+
# crafted branch/ref (e.g. containing <!channel>) can't inject mentions.
48+
esc() { printf '%s' "$1" | sed -e 's/&/\&amp;/g' -e 's/</\&lt;/g' -e 's/>/\&gt;/g'; }
49+
# Unique heredoc delimiter so a custom message can't collide with it.
50+
delim="SLACK_EOF_${RANDOM}${RANDOM}"
51+
{
52+
printf 'text<<%s\n' "$delim"
53+
if [ -n "$MESSAGE" ]; then
54+
printf '%s\n' "$MESSAGE"
55+
else
56+
printf ':actions: *Workflow failure* in %s: %s\n' "$(esc "$SOURCE_REPO")" "$(esc "$WORKFLOW_NAME")"
57+
printf 'on %s · %s · by %s\n' "$(esc "$EVENT_NAME")" "$(esc "$GIT_REF")" "$(esc "$ACTOR")"
58+
printf 'Run: %s\n' "$RUN_URL"
59+
if [ -n "$ISSUE_URL" ]; then
60+
printf 'Issue: %s\n' "$ISSUE_URL"
61+
else
62+
printf ':warning: No issue created\n'
63+
fi
64+
fi
65+
printf '%s\n' "$delim"
66+
} >> "$GITHUB_OUTPUT"
67+
2068
- name: Send Slack notification if workflow fails
2169
uses: slackapi/slack-github-action@45a88b9581bfab2566dc881e2cd66d334e621e2c # v3.0.3
2270
with:
@@ -25,4 +73,4 @@ runs:
2573
errors: true
2674
payload: |
2775
channel: ${{ toJSON(inputs.slack_channel_id) }}
28-
text: ${{ toJSON(inputs.message) }}
76+
text: ${{ toJSON(steps.build.outputs.text) }}

‎.github/instructions/content-guidelines.instructions.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,20 @@ The strategic priority is simplification: create less content and remove content
1919
* Would a typical internet user figure this out on their own by exploring the UI?
2020
* Is the information presented at the moment the reader actually needs it?
2121

22+
## Give opinionated, actionable guidance
23+
24+
This applies whenever you give the reader advice or present ways to accomplish a task.
25+
26+
* Be opinionated when there is a better way: when several approaches exist, recommend the best one and explain why, rather than presenting all options as equally valid. When they are genuinely equivalent, stay neutral.
27+
* Tell users the best practice AND how to follow it: whenever you state a best practice, pair it with concrete steps or an example so the reader can act on it, never the advice alone.
28+
29+
## Focus on the reader's purpose, not the product
30+
31+
Frame an article around what the reader is trying to accomplish, not the product or feature they use to do it. This applies when naming an article or deciding what a new or substantially reworked article should cover; do not use it to justify restructuring an article during a small edit.
32+
33+
* Title articles by the reader's goal, not the product or feature. For example, "Secure your enterprise", not "Use GitHub Advanced Security".
34+
* Scope articles around a task, not a product. When a task naturally spans multiple features or products, look for the opportunity to cover them together in one task-focused article or tutorial rather than splitting into per-product articles. Keep each article to a single purpose (the task): combine features only when they serve that same task, not to bundle unrelated capabilities.
35+
2236
## Intros: pull people in
2337

2438
This section applies mainly to the `intro` frontmatter field and, for conceptual articles, section openings.

‎.github/instructions/content.instructions.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,14 @@ Before committing content changes, always:
1616
3. **Verify [AUTOTITLE] links** point to existing articles
1717
4. **Run tests** on changed content: `npm run test -- src/content-render/tests/render-changed-and-deleted-files.ts`
1818

19+
## Accuracy and flagging uncertainty
20+
21+
AI assistants can produce plausible but incorrect information. To protect readers and writers:
22+
23+
* Never fabricate product behavior, settings, permissions, API parameters, or limits. If you cannot verify a detail from the source material or the product itself, say so instead of guessing.
24+
* Flag uncertainty at the level of the specific claim, not the whole article. Identify the individual sentence, step, value, or setting you are unsure about, rather than labeling an entire article as "needs review."
25+
* After writing or editing, give the writer a checklist of each specific claim to verify, noting where it appears (the exact step or sentence) and why it needs checking. Prioritize claims where being wrong could have serious consequences, such as security, authentication, permissions, billing, or any irreversible action, and recommend confirming those with the relevant product or engineering team.
26+
1927
## Bullet lists
2028

2129
The bulleted points in a bullet list should always be denoted in Markdown using an asterisk, not a hyphen.
@@ -107,6 +115,17 @@ For such content, DO NOT use in-article Liquid versioning such as `{% ifversion
107115

108116
All articles that are ONLY for GitHub Enterprise Server (GHES) should be versioned in the frontmatter using feature-based versioning defined in `data/features/`.
109117

118+
### Versioning for GHES content: always use feature-based versioning
119+
120+
If content is intended to ship to GitHub Enterprise Server, use **feature-based versioning (FBV)**.
121+
122+
* Do **not** suggest removing GHES frontmatter versioning or hardcode version strings (for example, `free-pro-team@latest`) just to make links or tests pass.
123+
* If CI fails because a GHES link cannot be built, treat that as a versioning mismatch—not a signal to de-scope GHES.
124+
* Add or reuse the appropriate feature flag in `data/features/`. Use it in `versions.feature` frontmatter when an article's availability follows the feature, and use Liquid conditionals only for version-specific blocks within a broader article.
125+
* Keep frontmatter and in-article versioning aligned so links render for every supported version.
126+
127+
For guidance, see [About feature-based versioning](https://docs.github.com/en/contributing/writing-for-github-docs/versioning-documentation#about-feature-based-versioning).
128+
110129
### FPT, GHEC, GHES articles
111130

112131
All articles that are versioned for all of FPT, GHEC, and GHES in the frontmatter MAY require certain blocks of content to be versioned using in-article Liquid versioning. Before recommending this, check if this is really the case.

‎.github/instructions/instruction-architecture.instructions.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
applyTo: ".github/instructions/**,.github/agents/**"
3+
---
4+
5+
# Editing Copilot content instruction and agent files
6+
7+
This applies when you add, edit, or remove a Copilot instruction or shared agent file that guides how **content** (articles, data files) is written. It does **not** apply to code instructions or agents owned by the engineering team (for example `code.instructions.md`).
8+
9+
When it applies, you **must** first read the instruction-architecture doc in full and follow it:
10+
11+
https://github.com/github/docs-team/blob/main/contributing-to-docs/docs-work/copilot-instruction-architecture.md
12+
13+
Read the current version every time (from a local `github/docs-team` checkout if you have one, otherwise fetch the URL); do not rely on your memory of it, because it changes. If you cannot access it, say so and stop rather than guessing.

‎.github/instructions/style-guide-summary.instructions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ For Liquid variable usage, reusables, linking conventions, bullet-list markers,
5959

6060
## Lists
6161

62-
* Capitalize the first letter of each list item.
62+
* Capitalize the first letter of each list item, including the first letter after the colon in a term definition list (for example, `* **Filesystem**: Grant read-only access...`).
6363
* Use periods only if the item is a complete sentence.
6464
* Introduce lists with a descriptive sentence, not vague phrases like "the following" in isolation.
6565

‎.github/workflows/auto-add-ready-for-doc-review.yml‎

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -27,18 +27,11 @@ jobs:
2727
- name: Check out repo
2828
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
2929

30-
- name: Generate GitHub App token
31-
id: app-token
32-
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
33-
with:
34-
app-id: ${{ secrets.DOCS_BOT_APP_ID }}
35-
private-key: ${{ secrets.DOCS_BOT_APP_PRIVATE_KEY }}
36-
3730
- name: Check team membership
3831
id: membership_check
3932
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
4033
with:
41-
github-token: ${{ steps.app-token.outputs.token }}
34+
github-token: ${{ secrets.DOCS_BOT_PAT_BASE }}
4235
script: |
4336
try {
4437
await github.rest.teams.getMembershipForUserInOrg({
@@ -55,7 +48,7 @@ jobs:
5548
- name: Add ready-for-doc-review label
5649
if: steps.membership_check.outputs.result == 'false'
5750
env:
58-
GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
51+
GITHUB_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
5952
PR_URL: ${{ github.event.pull_request.html_url }}
6053
run: |
6154
gh pr edit $PR_URL --add-label ready-for-doc-review

‎.github/workflows/benchmark-pages.yml‎

Lines changed: 7 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -24,15 +24,6 @@ jobs:
2424
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
2525
with:
2626
persist-credentials: 'false'
27-
- name: Generate GitHub App token
28-
id: app-token
29-
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
30-
with:
31-
app-id: ${{ secrets.DOCS_BOT_APP_ID }}
32-
private-key: ${{ secrets.DOCS_BOT_APP_PRIVATE_KEY }}
33-
owner: github
34-
repositories: docs-engineering
35-
3627
- uses: ./.github/actions/node-npm-setup
3728

3829
- name: Build
@@ -58,7 +49,7 @@ jobs:
5849
- name: Check results and create issue if needed
5950
if: always()
6051
env:
61-
GH_TOKEN: ${{ steps.app-token.outputs.token }}
52+
GH_TOKEN: ${{ secrets.DOCS_BOT_PAT_BASE }}
6253
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
6354
run: |
6455
echo "Reading benchmark results..."
@@ -166,12 +157,14 @@ jobs:
166157
echo "Done creating issue"
167158
fi
168159
169-
- uses: ./.github/actions/slack-alert
160+
- uses: ./.github/actions/create-workflow-failure-issue
161+
id: create-failure-issue
170162
if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
171163
with:
172-
slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
164+
token: ${{ secrets.DOCS_BOT_PAT_BASE }}
173165

174-
- uses: ./.github/actions/create-workflow-failure-issue
166+
- uses: ./.github/actions/slack-alert
175167
if: ${{ failure() && github.event_name != 'workflow_dispatch' }}
176168
with:
177-
token: ${{ steps.app-token.outputs.token }}
169+
slack_token: ${{ secrets.SLACK_DOCS_BOT_TOKEN }}
170+
issue_url: ${{ steps.create-failure-issue.outputs.issue_url }}

0 commit comments

Comments
 (0)