You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This repository contains code to run the GitHub Docs site on docs.github.com, as well as the content that the site displays. We write the code in JavaScript and TypeScript, and we write the content primarily in Markdown.
8
+
9
+
## Creating a pull request
10
+
11
+
When you create a pull request:
12
+
13
+
1.**Always** make the first line of the PR description the following (in italics):
14
+
15
+
`_Copilot Chat generated this pull request._`
16
+
17
+
2. Optionally, you may include a collapsed section summarizing the prompt or discussion with Copilot Chat:
18
+
19
+
```markdown
20
+
<details><summary>Prompt summary - submitted by @GITHUB-USER-ID</summary>
21
+
22
+
> [Prompt summary text here]
23
+
24
+
</details>
25
+
```
26
+
27
+
This helps reviewers understand the context and intent behind the automated changes.
28
+
29
+
3. Label with "llm-generated".
30
+
4. If an issue exists, include "fixes owner/repo#issue" or "towards owner/repo#issue" as appropriate.
For code reviews, follow guidelines, tests, and validate instructions. For creating or updating pull requests or branches, follow the steps instructions.
8
+
9
+
## Guidelines
10
+
11
+
- If available, use ripgrep (`rg`) instead of `grep`.
12
+
- Make sure to always _escape backticks_ when using gh cli.
13
+
- All scripts should be listed in `package.json` and use `tsx`.
14
+
- Whenever you create or comment on an issue or pull request, indicate you are an LLM.
15
+
- Be careful fetching full HTML pages off the internet. Prefer to use gh cli whenever possible for github.com. Limit the number of tokens when grabbing HTML.
16
+
- Avoid pull requests with over 300 lines of code changed. When significantly larger, offer to split up into smaller pull requests if possible.
17
+
- All new code should be written in TypeScript and not JavaScript.
18
+
- We use absolute imports, relative to the `src` directory, using the `@` symbol. For example, `getRedirect` which lives in `src/redirects/lib/get-redirect.js` can be imported with `import getRedirect from '@/redirects/lib/get-redirect'`. The same rule applies for TypeScript (`.ts`) imports, e.g. `import type { GeneralSearchHit } from '@/search/types'`
19
+
20
+
## Tests
21
+
22
+
We use `vitest` to write unit tests. Tests live in their own files in the `tests` subdirectory of a source (src) directory, e.g. `src/search/tests/api-ai-search.ts`. For integration tests, we can use the mock server in `src/tests/mocks/start-mock-server.ts` to mock external requests. For UI rendering tests, we use `playwright` and write tests in `src/fixtures/tests/playwright-rendering.spec.ts`
23
+
24
+
-`npm run test`: For all unit tests
25
+
- You can pass specific paths, e.g. `npm run test -- src/search/tests/ai-search-proxy`
26
+
- You can add `--silent=false` to include `console.log` debugging.
27
+
-`npm run build && npm run playwright-test -- playwright-rendering`: You need to build for changes outside of the test to be picked up. We use playwright for all rendering and end-to-end tests
28
+
- You can add `--ui` to keep open `localhost:4000` which can be viewed in a simple browser for debugging UI state.
29
+
-`npm run dev` to start the development server on `localhost:4000`.
30
+
-`ROOT=src/fixtures/fixtures TRANSLATIONS_FIXTURE_ROOT=src/fixtures/fixtures/translations vitest src/fixtures/tests` for tests that involve fixtures.
31
+
32
+
## Validate
33
+
34
+
Run the following commands to validate your changes:
35
+
36
+
-`npm run tsc`
37
+
-`npm run build`
38
+
-`npm run prettier`
39
+
-`npm run lint`: you can include `-- --fix`
40
+
41
+
## Steps
42
+
43
+
0. Ask the human if they would like you to follow these steps.
44
+
1. If this is new work, make sure you have the latest changes by running `git checkout main && git pull`. If this is existing work, update the branch you are working on with the head branch -- usually `main`.
45
+
2. If the human provides a GitHub issue, use gh cli to read the issue and all comments.
46
+
3. Begin by evaluating impact, effort, and estimate non-test lines of code that will change. Ask for more context and examples if needed.
47
+
4. If you are running in agentic mode, _stop_ at this point and request approval from the human.
48
+
5. If you need to add or change tests, work on tests before implementing.
49
+
6. Implement the changes needed. If you are running in agentic mode, _stop_ and ask questions at decision points. Please list the options, pros and cons for each decision needed.
50
+
7. Validate your changes before making any commits. See "Validate".
51
+
8. Validate that any new or changed tests pass. See "Tests".
52
+
9. Validate that these changes meet our guidelines. See "Guidelines".
53
+
10. If you are running in agentic mode, _stop_ at this point and request review before continuing. Suggest how the human should review the changes.
54
+
11. If a branch and pull request already exist, commit and push, then _concisely_ comment on the pull request that you are an LLM and what changes you made and why.
55
+
12. If this is new work and no pull request exists yet, make a pull request:
56
+
- label "llm-generated"
57
+
- draft mode
58
+
- include "fixes owner/repo#issue" or "towards owner/repo#issue" as appropriate
59
+
13. If you are in agentic mode, offer to wait for CI to run and check that it passes. If the human agrees, verify in CI: `sleep 240 && gh pr checks $number`. Address all failures, don't assume they're flakes.
60
+
14. If you are in agentic mode, offer to do any or all of:
61
+
- mark the pull request as ready,
62
+
- assign the issue to the human if it is not already assigned,
63
+
-_concisely_ comment on the issue explaining the change, indicating you are an LLM.
This repository contains code to run the GitHub Docs site on docs.github.com, as well as the content that is displayed on the site. The code is written in JavaScript and TypeScript, and the content is primarily written in Markdown.
1
+
---
2
+
applyTo: "content/**,data/**,**/*.md"
3
+
---
2
4
3
-
Changes to files in `src/*` or files with `.ts` or `.js` extensions are likely code-related changes. Please follow the engineering guidelines below when making changes to these files.
5
+
# Copilot content instructions for docs.github.com
4
6
5
-
Changes to files in `content/*` and `data/*` are likely content-related changes. Content changes include updates to articles, reusable content, and data files that define variables used in articles. Please follow the content guidelines below when making changes to these files.
7
+
**When to use**: Content editing, documentation writing, Markdown files
8
+
**Key indicators**: Changes to .md files, creating articles, updating documentation
6
9
7
-
## Engineering guidelines
10
+
## Testing Content changes
8
11
9
-
### Scripts
10
-
11
-
All scripts can be found in `package.json`.
12
-
13
-
To validate any code changes:
14
-
-`npm run tsc`
15
-
-`npm run build`
16
-
-`npm run prettier`
17
-
-`npm run lint`: you can include `-- --fix`
18
-
19
-
To validate specific changes,
20
-
-`npm run test`: For all unit tests
21
-
- You can pass specific paths, e.g. `npm run test -- src/search/tests/ai-search-proxy`
22
-
- You can add `--silent=false` to include `console.log` debugging.
23
-
-`npm run build && npm run playwright-test -- playwright-rendering`: You need to build for changes outside of the test to be picked up. We use playwright for all rendering and end-to-end tests
24
-
- You can add `--ui` to keep open `localhost:4000` which can be viewed in a simple browser for debugging UI state.
25
-
-`npm run dev` to start the development server on `localhost:4000`.
26
-
27
-
### Imports
28
-
29
-
We use absolute imports, relative to the `src` directory, using the `@` symbol.
30
-
31
-
For example, `getRedirect` which lives inn `src/redirects/lib/get-redirect.js` can be imported with `import getRedirect from '@/redirects/lib/get-redirect'`.
32
-
33
-
The same rule applies for TypeScript (`.ts`) imports, e.g. `import type { GeneralSearchHit } from '@/search/types'`
34
-
35
-
### Testing changes
36
-
37
-
We use `vitest` to write unit tests. Tests live in their own files in the `tests` subdirectory of a source (src) directory, e.g. `src/search/tests/api-ai-search.ts`.
38
-
39
-
For integration tests, we can use the mock server in `src/tests/mocks/start-mock-server.ts` to mock exteneral requests.
40
-
41
-
For UI rendering tests, we use `playwright` and write tests in `src/fixtures/tests/playwright-rendering.spec.ts`
12
+
Before committing content changes, always:
42
13
43
-
## Content guidelines
14
+
1.**Use the content linter** to validate content: `npm run lint-content -- --paths <file-paths>`
15
+
2.**Check for proper variable usage** in your content
16
+
3.**Verify [AUTOTITLE] links** point to existing articles
17
+
4.**Run tests** on changed content: `npm run test -- src/content-render/tests/render-changed-and-deleted-files.js`
44
18
45
-
###Bullet lists
19
+
## Bullet lists
46
20
47
21
The bulleted points in a bullet list should always be denoted in Markdown using an asterisk, not a hyphen.
48
22
49
-
###Using variables
23
+
## Using variables
50
24
51
25
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.
52
26
53
-
**Important**: Variables must be used in all content, including reusable content, data files, and regular articles. The only exceptions are the `title` field in frontmatter metadata and any file in the `content/site-policy` directory.
27
+
**Important**: You must use variables in all content, including reusable content, data files, and regular articles. The only exceptions are the `title` field in frontmatter metadata and any file in the `content/site-policy` directory.
54
28
55
29
For example:
56
30
@@ -64,7 +38,7 @@ For example:
64
38
|`{% data variables.enterprise.prodname_managed_user %}`| managed user account | data/variables/enterprise.yml |
65
39
|`{% data variables.code-scanning.codeql_workflow %}`| CodeQL analysis workflow | data/variables/code-scanning.yml |
66
40
67
-
There are many more variables. These are stored in various YAML files within the `data/variables` directory.
41
+
There are many more variables. We store these in various YAML files within the `data/variables` directory.
68
42
69
43
**How to find variables**: Check the `data/variables` directory for existing variables before writing hardcoded text. Common variable files include:
70
44
@@ -73,7 +47,7 @@ There are many more variables. These are stored in various YAML files within the
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.
79
53
@@ -84,21 +58,21 @@ Examples where you should create a reusable:
84
58
* 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.
85
59
* 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.
86
60
87
-
###Links to other articles
61
+
## Links to other articles
88
62
89
63
`[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.
90
64
91
65
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.
92
66
93
-
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.
67
+
Never use the `{% link %}` Liquid tag for internal documentation links. The `[AUTOTITLE]` placeholder automatically pulls the correct title and ensures that links remain valid when titles change.
94
68
95
69
Examples:
96
70
97
71
* ✅ Correct: `For more information, see [AUTOTITLE](/copilot/using-github-copilot).`
98
72
* ❌ Incorrect: `For more information, see [Using GitHub Copilot](/copilot/using-github-copilot).`
99
73
* ❌ Incorrect: `For more information, see {% link /copilot/using-github-copilot %}.`
100
74
101
-
###Parenthetical dashes
75
+
## Parenthetical dashes
102
76
103
77
Where a sentence of normal body text contains a parenthetical dash, the dash should always be an em dash without spaces at either side. This rule does not apply to text within code blocks.
104
78
@@ -110,31 +84,3 @@ Examples:
110
84
* ❌ Incorrect: "The cat – which sat on a branch – smiled with a broad grin." (en dash with spaces)
111
85
* ❌ Incorrect: "The cat-which sat on a branch-smiled with a broad grin." (hyphen without spaces)
112
86
* ❌ Incorrect: "The cat - which sat on a branch - smiled with a broad grin." (hyphen with spaces)
113
-
114
-
## Creating a pull request
115
-
116
-
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):
117
-
118
-
`_This pull request was created as a result of the following prompt in Copilot Chat._`
119
-
120
-
Then, within a collapsed section, quote the original prompt from Copilot Chat:
121
-
122
-
```markdown
123
-
<details>
124
-
<summary>Original prompt - submitted by @GITHUB-USER-ID</summary>
125
-
126
-
> [Original prompt text here]
127
-
128
-
</details>
129
-
```
130
-
131
-
This helps reviewers understand the context and intent behind the automated changes.
132
-
133
-
### Testing Content changes
134
-
135
-
Before committing content changes, always:
136
-
137
-
1.**Use the content linter** to validate content: `npm run lint-content -- --paths <file-paths>`
138
-
2.**Check for proper variable usage** in your content
139
-
3.**Verify [AUTOTITLE] links** point to existing articles
140
-
4.**Run tests** on changed content: `npm run test -- src/content-render/tests/render-changed-and-deleted-files.js`
intro: 'You can configure monitoring and alerting so that you''re aware of potential issues before they negatively impact application performance or availability.'
4
+
versions:
5
+
ghes: '*'
6
+
topics:
7
+
- Enterprise
8
+
shortTitle: About monitoring
9
+
---
10
+
11
+
## Metrics
12
+
13
+
{% ifversion ghes-opentelemetry %}OpenTelemetry metrics were introduced in {% data variables.product.prodname_ghe_server %} 3.18 and are the future foundation for monitoring your {% data variables.product.prodname_ghe_server %} instance. {% endif %}
14
+
Collectd metrics {% ifversion ghes-opentelemetry %}will continue to be gathered by default, but we expect collectd metrics to be discontinued in a future release.{% else %}provide monitoring capabilities for your {% data variables.product.prodname_ghe_server %} instance.{% endif %}
15
+
16
+
{% ifversion ghes-opentelemetry %}For more information about OpenTelemetry metrics, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/opentelemetry-metrics/about-opentelemetry-metrics).{% endif %}
17
+
18
+
For more information about Collectd metrics, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/collectd-metrics/about-collectd-metrics).
19
+
20
+
## Dashboards
21
+
22
+
The {% data variables.enterprise.management_console %} provides built-in dashboards that visualize metrics to help you troubleshoot performance issues and better understand how your {% data variables.product.prodname_ghe_server %} appliance is being used. The data behind the graphs is gathered by the monitoring services and sampled regularly.
23
+
24
+
For more information about the monitor dashboards, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-the-monitor-dashboards).
25
+
26
+
## System Logs
27
+
28
+
{% data variables.product.prodname_ghe_server %} maintains system logs that can be used to monitor system events and troubleshoot issues. These logs provide detailed information about various system processes and can be valuable for debugging and monitoring purposes.
29
+
30
+
For more information about system logs, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/about-system-logs).
31
+
32
+
## Troubleshooting resource allocation problems
33
+
34
+
Resource allocation problems can impact the performance and availability of your {% data variables.product.prodname_ghe_server %} instance. Understanding how to identify and resolve these issues is crucial for maintaining optimal system performance.
35
+
36
+
For more information about troubleshooting resource allocation problems, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/troubleshooting-resource-allocation-problems).
37
+
38
+
## Generating a Health Check for your enterprise
39
+
40
+
A health check provides a comprehensive overview of your {% data variables.product.prodname_ghe_server %} instance's current state and can help identify potential issues before they become critical.
41
+
42
+
For more information about generating a health check, see [AUTOTITLE](/admin/monitoring-and-managing-your-instance/monitoring-your-instance/generating-a-health-check-for-your-enterprise).
0 commit comments