Skip to content

Commit 33b4d28

Browse files
docs-botdocs-bot
authored
Merge pull request #38787 from github/repo-sync
Repo sync
2 parents 67c452b + 75679a7 commit 33b4d28

File tree

2 files changed

+213
-12
lines changed

2 files changed

+213
-12
lines changed

‎.github/copilot-instructions.md

Lines changed: 94 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,107 @@
11
This documentation repository consists mainly of content written in Markdown format. These files are converted into HTML for displaying on a website. Most Markdown files become a single article on the documentation site. Other files contain reusable content which is inserted into multiple articles. The repository also contains YAML files (e.g. for variable text), image files, JavaScript/TypeScript files, etc.
22

3+
## Content guidelines
4+
5+
### Bullet lists
6+
7+
The bulleted points in a bullet list should always be denoted in Markdown using an asterisk, not a hyphen.
8+
39
### Using variables
410

5-
Within Markdown files, with the exception of the `title` field in the metadata at the start of a file, always use the Liquid syntax variables rather than text if a variable has been defined for that text. For example:
11+
Within Markdown files, with the exception of the `title` field in the metadata at the start of a file, **always use the Liquid syntax variables rather than text** if a variable has been defined for that text. This ensures consistency and makes it easier to update product names globally.
12+
13+
**Important**: Variables must be used in all content, including reusable content, data files, and regular articles. The only exception is the `title` field in frontmatter metadata.
614

7-
| Use this variable | Don't use this text | File where variable is defined |
8-
| --- | --- | --- |
9-
| `{% data variables.product.prodname_dotcom %}` | GitHub | data/variables/product.yml |
10-
| `{% data variables.product.prodname_ghe_server %}` | GitHub Enterprise Server | data/variables/product.yml |
11-
| `{% data variables.product.prodname_copilot_short %}` | Copilot | data/variables/product.yml |
12-
| `{% data variables.product.prodname_copilot %}` | GitHub Copilot | data/variables/product.yml |
13-
| `{% data variables.copilot.copilot_code-review_short %}` | Copilot code review | data/variables/copilot.yml |
14-
| `{% data variables.enterprise.prodname_managed_user %}` | managed user account | data/variables/enterprise.yml |
15-
| `{% data variables.code-scanning.codeql_workflow %}` | CodeQL analysis workflow | data/variables/code-scanning.yml |
15+
For example:
16+
17+
| Use this variable | Don't use this text | File where variable is defined |
18+
| -------------------------------------------------------- | ------------------------ | -------------------------------- |
19+
| `{% data variables.product.github %}` | GitHub | data/variables/product.yml |
20+
| `{% data variables.product.prodname_ghe_server %}` | GitHub Enterprise Server | data/variables/product.yml |
21+
| `{% data variables.product.prodname_copilot_short %}` | Copilot | data/variables/product.yml |
22+
| `{% data variables.product.prodname_copilot %}` | GitHub Copilot | data/variables/product.yml |
23+
| `{% data variables.copilot.copilot_code-review_short %}` | Copilot code review | data/variables/copilot.yml |
24+
| `{% data variables.enterprise.prodname_managed_user %}` | managed user account | data/variables/enterprise.yml |
25+
| `{% data variables.code-scanning.codeql_workflow %}` | CodeQL analysis workflow | data/variables/code-scanning.yml |
1626

1727
There are many more variables. These are stored in various YAML files within the `data/variables` directory.
1828

29+
**How to find variables**: Check the `data/variables` directory for existing variables before writing hardcoded text. Common variable files include:
30+
31+
* `data/variables/product.yml` - Product names and variations
32+
* `data/variables/copilot.yml` - Copilot-specific terms
33+
* `data/variables/enterprise.yml` - Enterprise-specific terms
34+
* `data/variables/code-scanning.yml` - Code scanning terms
35+
36+
### Reusable text
37+
38+
Reusables are long strings of reusable text, such as paragraphs or procedural lists, that are referenced in multiple content files. This makes it easier for us to maintain content and ensure that it is accurate across all files where the content is needed.
39+
40+
Each reusable lives in its own Markdown file. The path and filename of each reusable determines what its path will be in the data object. For example, a file named `/data/reusables/foo/bar.md` will be accessible as `{% data reusables.foo.bar %}` in articles.
41+
42+
Examples where you should create a reusable:
43+
44+
* You are documenting a new feature for a public preview. You need to create a note to display in all new articles about the new feature. Create a new reusable for the note and use it in all articles where it is needed.
45+
* You are documenting billing for a new feature and need to briefly mention how the feature is billed and link to content about billing in several articles. Create a new reusable with the brief mention and a link to the content on billing. Aim to use the reusable in all places where you want to mention billing for the feature.
46+
1947
### Links to other articles
2048

21-
`[AUTOTITLE]` is the correct way to specify the title of a linked article, when that article is another page on the docs.github.com site. Do not suggest replacing the placeholder link text `[AUTOTITLE]` with the actual page title or using the `{% link %}` Liquid tag.
49+
`[AUTOTITLE]` is the **only correct way** to specify the title of a linked article when that article is another page on the docs.github.com site.
50+
51+
You can replace the placeholder link text `[AUTOTITLE]` only when linking to an anchor in the same article or when linking to an anchor in another article and the actual article title would be confusing.
52+
53+
Never use the `{% link %}` Liquid tag for internal documentation links. The `[AUTOTITLE]` placeholder automatically pulls the correct title and ensures links remain valid when titles change.
54+
55+
Examples:
56+
57+
* ✅ Correct: `For more information, see [AUTOTITLE](/copilot/using-github-copilot).`
58+
* ❌ Incorrect: `For more information, see [Using GitHub Copilot](/copilot/using-github-copilot).`
59+
* ❌ Incorrect: `For more information, see {% link /copilot/using-github-copilot %}.`
2260

2361
### Creating a pull request
2462

25-
When creating a pull request as a result of a request to do so in Copilot Chat, the first line of the PR description should always be the following (in italics): `_This pull request was created as a result of the following prompt in Copilot Chat._` Then, within a collapsed section, quote the original prompt from Copilot Chat. The clickable text that expands the collapsed section should be: Original prompt - submitted by @GITHUB-USER-ID. Where @GITHUB-USER-ID is the @ user name of the GitHub user who submitted the prompt.
63+
When creating a pull request as a result of a request to do so in Copilot Chat, the first line of the PR description should **always** be the following (in italics):
64+
65+
`_This pull request was created as a result of the following prompt in Copilot Chat._`
66+
67+
Then, within a collapsed section, quote the original prompt from Copilot Chat:
68+
69+
```markdown
70+
<details>
71+
<summary>Original prompt - submitted by @GITHUB-USER-ID</summary>
72+
73+
> [Original prompt text here]
74+
75+
</details>
76+
```
77+
78+
This helps reviewers understand the context and intent behind the automated changes.
79+
80+
## Development and testing guidelines
81+
82+
### Content changes
83+
84+
Before committing content changes, always:
85+
86+
1. **Use the content linter** to validate content: `npm run lint-content -- --paths <file-paths>`
87+
2. **Check for proper variable usage** in your content
88+
3. **Verify [AUTOTITLE] links** point to existing articles
89+
4. **Run tests** on changed content: `npm run test -- src/content-render/tests/render-changed-and-deleted-files.js`
90+
91+
### Script and code changes
92+
93+
For TypeScript, JavaScript, and SCSS files:
94+
95+
1. **Run Prettier** to check formatting: `npm run prettier-check`
96+
2. **Run the linter**: `npm run lint`
97+
3. **Run TypeScript checks**: `npm run tsc`
98+
4. **Run relevant tests**: `npm test`
99+
100+
### Environment setup
101+
102+
When testing changes in your development environment:
103+
104+
1. Install dependencies: `npm ci`
105+
2. For content changes, ensure the content linter runs successfully
106+
3. For script changes, ensure all formatting and linting checks pass
107+
4. Always verify your changes don't break existing functionality

‎.github/workflows/copilot-setup-steps.yml

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
name: 'Copilot Environment Setup'
2+
3+
# **What it does**: Sets up the environment for Copilot coding agent to test content and script changes.
4+
# **Why we have it**: Ensures Copilot can validate content with linters and formatters before making changes.
5+
# **Who does it impact**: Copilot coding agent and developers using repository custom instructions.
6+
7+
on:
8+
workflow_dispatch:
9+
inputs:
10+
check_content:
11+
description: 'Check content files with content linter'
12+
required: false
13+
default: true
14+
type: boolean
15+
check_scripts:
16+
description: 'Check TypeScript/JavaScript/SCSS files with prettier and linter'
17+
required: false
18+
default: true
19+
type: boolean
20+
paths:
21+
description: 'Specific file paths to check (space-separated), or leave empty for changed files'
22+
required: false
23+
type: string
24+
25+
permissions:
26+
contents: read
27+
28+
jobs:
29+
copilot-setup-steps:
30+
if: github.repository == 'github/docs-internal'
31+
runs-on: ${{ github.repository == 'github/docs-internal' && 'ubuntu-20.04-xl' || 'ubuntu-latest' }}
32+
33+
steps:
34+
- name: Check out repo
35+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
36+
37+
- name: Set up Node and dependencies
38+
uses: ./.github/actions/node-npm-setup
39+
40+
- name: Get changed files if no specific paths provided
41+
if: inputs.paths == ''
42+
id: changed_files
43+
uses: ./.github/actions/get-changed-files
44+
with:
45+
files: |
46+
content/**
47+
data/**
48+
src/**/*.{ts,tsx,js,mjs}
49+
**/*.scss
50+
51+
- name: Set file paths for checking
52+
id: set_paths
53+
run: |
54+
if [ -n "${{ inputs.paths }}" ]; then
55+
echo "files_to_check=${{ inputs.paths }}" >> $GITHUB_OUTPUT
56+
else
57+
echo "files_to_check=${{ steps.changed_files.outputs.filtered_changed_files }}" >> $GITHUB_OUTPUT
58+
fi
59+
60+
- name: Run content linter on content/data files
61+
if: inputs.check_content == true && (contains(steps.set_paths.outputs.files_to_check, 'content/') || contains(steps.set_paths.outputs.files_to_check, 'data/'))
62+
env:
63+
FILES_TO_CHECK: ${{ steps.set_paths.outputs.files_to_check }}
64+
run: |
65+
# Filter for content and data files only
66+
CONTENT_FILES=$(echo "$FILES_TO_CHECK" | tr ' ' '\n' | grep -E '^(content|data)/' | tr '\n' ' ' || true)
67+
if [ -n "$CONTENT_FILES" ]; then
68+
echo "Running content linter on: $CONTENT_FILES"
69+
npm run lint-content -- --paths $CONTENT_FILES
70+
else
71+
echo "No content or data files to check"
72+
fi
73+
74+
- name: Run prettier check on script files
75+
if: inputs.check_scripts == true
76+
env:
77+
FILES_TO_CHECK: ${{ steps.set_paths.outputs.files_to_check }}
78+
run: |
79+
# Filter for TypeScript, JavaScript, and SCSS files
80+
SCRIPT_FILES=$(echo "$FILES_TO_CHECK" | tr ' ' '\n' | grep -E '\.(ts|tsx|js|mjs|scss)$' | tr '\n' ' ' || true)
81+
if [ -n "$SCRIPT_FILES" ]; then
82+
echo "Running prettier check on: $SCRIPT_FILES"
83+
npm run prettier-check -- $SCRIPT_FILES
84+
else
85+
echo "No script files to check with prettier"
86+
fi
87+
88+
- name: Run ESLint on script files
89+
if: inputs.check_scripts == true
90+
env:
91+
FILES_TO_CHECK: ${{ steps.set_paths.outputs.files_to_check }}
92+
run: |
93+
# Filter for TypeScript and JavaScript files only (ESLint doesn't handle SCSS)
94+
SCRIPT_FILES=$(echo "$FILES_TO_CHECK" | tr ' ' '\n' | grep -E '\.(ts|tsx|js|mjs)$' | tr '\n' ' ' || true)
95+
if [ -n "$SCRIPT_FILES" ]; then
96+
echo "Running ESLint on: $SCRIPT_FILES"
97+
npx eslint $SCRIPT_FILES
98+
else
99+
echo "No JavaScript/TypeScript files to lint"
100+
fi
101+
102+
- name: Run TypeScript compiler check
103+
if: inputs.check_scripts == true && (contains(steps.set_paths.outputs.files_to_check, '.ts') || contains(steps.set_paths.outputs.files_to_check, '.tsx'))
104+
run: |
105+
echo "Running TypeScript compiler check"
106+
npm run tsc
107+
108+
- name: Environment setup summary
109+
run: |
110+
echo "✅ Copilot environment setup completed successfully!"
111+
echo ""
112+
echo "Available commands for content validation:"
113+
echo "- Content linting: npm run lint-content -- --paths <file-paths>"
114+
echo "- Prettier formatting: npm run prettier-check -- <file-paths>"
115+
echo "- ESLint: npm run lint"
116+
echo "- TypeScript check: npm run tsc"
117+
echo "- All tests: npm test"
118+
echo ""
119+
echo "For more guidance, see .github/copilot-instructions.md"

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy