Skip to content

Commit 3b7d170

Browse files
docs-botdocs-bot
authored
Merge pull request #42235 from github/repo-sync
Repo sync
2 parents 722b7bb + f790db7 commit 3b7d170

File tree

14 files changed

+2015
-236
lines changed

14 files changed

+2015
-236
lines changed

‎src/ai-tools/README.md‎

Lines changed: 165 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,183 @@
11
# AI-powered tools
22

3-
A CLI tool for using AI to edit documentation according to defined prompts.
3+
The ai-tools subject provides CLI tools for using AI to edit and refine documentation based on prompt-driven guidelines. It integrates with GitHub Models API to apply automated improvements to content files.
44

5-
This tool refines content files using AI based on an (extensible) set of prompt-driven guidelines. The default is versioning refinement. In the future we might add: scannability, readability, style, technical accuracy.
5+
## Purpose & Scope
66

7-
This script calls the [Models API](https://docs.github.com/en/rest/models/inference?apiVersion=2022-11-28#run-an-inference-request). It requires a personal access token with Models scopes in your `.env` file.
7+
This subject is responsible for:
8+
- AI-powered content refinement (versioning, intro, etc.)
9+
- Prompt-driven content editing with LLMs
10+
- Integration with GitHub Models API
11+
- Copilot Spaces export and conversion to prompts
12+
- Automated content quality improvements
13+
- Extensible prompt system for different refinement types
814

9-
## Usage
15+
Current refinements: versioning, intro. Future: scannability, readability, style, technical accuracy.
1016

11-
```sh
12-
<<<<<<< HEAD:src/ai-editors/README.md
13-
tsx src/ai-editors/scripts/ai-edit.ts --editor <type> --response <type> --files <file1.md>
14-
||||||| 5ae4ec0f5cb:src/ai-editors/README.md
15-
tsx src/ai-editors/scripts/ai-edit.js --editor <type> --response <type> --files <file1.md>
16-
=======
17+
## Architecture & Key Assets
18+
19+
### Key capabilities and their locations
20+
21+
- `scripts/ai-tools.ts` - Main CLI tool for running AI refinements
22+
- `lib/call-models-api.ts` - Client for GitHub Models API inference
23+
- `lib/prompt-utils.ts` - Loads prompts and executes refinements
24+
- `prompts/*.md` - Prompt templates for different refinement types
25+
26+
## Setup & Usage
27+
28+
### Requirements
29+
30+
Add GitHub token with Models scopes to `.env`:
31+
32+
```bash
33+
GITHUB_TOKEN=ghp_your_token_here
34+
```
35+
36+
### Running refinements
37+
38+
```bash
1739
# Direct command
18-
tsx src/ai-tools/scripts/ai-tools.ts --refine <type> --files <file1.md>
40+
tsx src/ai-tools/scripts/ai-tools.ts --refine versioning --files content/path/to/file.md
1941

20-
# Or via npm script
21-
npm run ai-tools -- --refine <type> --files <file1.md>
22-
>>>>>>> origin/main:src/ai-tools/README.md
42+
# Via npm script
43+
npm run ai-tools -- --refine versioning --files content/path/to/file.md
2344
```
2445

25-
* `--files, -f`: One or more content file paths to process (required).
26-
* `--refine, -r`: Specify one or more refinement types (default: `versioning`).
46+
### Options
2747

28-
**Examples:**
48+
- `--files, -f`: One or more content file paths (required)
49+
- `--refine, -r`: Refinement type(s) - `versioning`, `intro` (default: `versioning`)
50+
- `--write, -w`: Write changes to files (default: false, shows diff only)
51+
- `--verbose, -v`: Verbose output for debugging
52+
- `--space, -s`: Use Copilot Space as prompt
53+
- `--exportSpace`: Export Copilot Space to prompt file
2954

30-
```sh
31-
<<<<<<< HEAD:src/ai-editors/README.md
32-
tsx src/ai-editors/scripts/ai-edit.ts --files content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md --editor versioning --response list
33-
||||||| 5ae4ec0f5cb:src/ai-editors/README.md
34-
tsx src/ai-editors/scripts/ai-edit.js --files content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md --editor versioning --response list
35-
=======
36-
# Direct command
37-
tsx src/ai-tools/scripts/ai-tools.ts --files content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md --refine versioning
55+
### Examples
3856

39-
# Via npm script
40-
npm run ai-tools -- --files content/copilot/tutorials/coding-agent/get-the-best-results.md --refine intro
41-
>>>>>>> origin/main:src/ai-tools/README.md
57+
Refine versioning in a file:
58+
```bash
59+
npm run ai-tools -- --files content/copilot/tutorials/coding-agent/get-the-best-results.md --refine versioning
4260
```
4361

44-
## Requirements
62+
Refine intro:
63+
```bash
64+
npm run ai-tools -- --files content/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo.md --refine intro
65+
```
66+
67+
Multiple files:
68+
```bash
69+
npm run ai-tools -- --files file1.md file2.md file3.md --refine versioning
70+
```
71+
72+
Write changes (not just preview):
73+
```bash
74+
npm run ai-tools -- --files content/path/to/file.md --refine versioning --write
75+
```
76+
77+
## Data & External Dependencies
78+
79+
### Data inputs
80+
- Content markdown files with frontmatter
81+
- Prompt templates in `prompts/` directory
82+
- GitHub Models API for inference
83+
84+
### Dependencies
85+
- GitHub Models API - Requires `GITHUB_TOKEN` with Models scopes
86+
- `commander` - CLI argument parsing
87+
- `dotenv` - Environment variable loading
88+
- Copilot Spaces (optional) - Can export/import prompts
89+
90+
### Data outputs
91+
- Refined markdown content (preview or written to files)
92+
- Diffs showing proposed changes
93+
- Merged frontmatter updates
94+
95+
## Cross-links & Ownership
96+
97+
### Related subjects
98+
- [`src/content-render`](../content-render/README.md) - Content parsing and rendering
99+
- Content files in `content/` - Target of refinements
100+
101+
### Internal documentation
102+
- [GitHub Models API docs](https://docs.github.com/en/rest/models/inference)
103+
- Copilot Spaces for prompt management
104+
105+
### Ownership
106+
- Team: Docs Content (for use and development)
107+
- Note: These tools are for the docs-content team. We welcome them to use Copilot to support and develop these tools, but docs-engineering is largely hands off.
108+
109+
## Current State & Next Steps
110+
111+
### Available refinement types
112+
113+
Current prompts:
114+
- `versioning` - Refines version-related content
115+
- `intro` - Improves article introductions
116+
117+
Each prompt defines:
118+
- Instructions for the LLM
119+
- Expected output format
120+
- Quality criteria
121+
122+
### Adding new refinements
123+
124+
1. Create prompt file in `prompts/` (e.g., `readability.md`).
125+
2. Write prompt instructions and examples.
126+
3. Test with Models UI first.
127+
4. Use `--refine readability` to apply.
128+
129+
Prompt template in `prompts/prompt-template.yml`.
130+
131+
### Copilot Spaces integration
132+
133+
Export Space to prompt:
134+
```bash
135+
npm run ai-tools -- --exportSpace space-id --output prompts/my-prompt.md
136+
```
137+
138+
Use Space as prompt:
139+
```bash
140+
npm run ai-tools -- --space space-id --files content/path/to/file.md
141+
```
142+
143+
### Known limitations
144+
- Requires GitHub token with Models scopes
145+
- API rate limits apply
146+
- Quality depends on prompt engineering
147+
- Currently manual execution (not in CI)
148+
- No automated testing/evals yet
149+
150+
### Best practices
151+
152+
**Prompt engineering:**
153+
- Test prompts in GitHub Models UI first
154+
- Include clear examples in prompts
155+
- Define expected output format
156+
- Iterate on prompts based on results
157+
158+
**File selection:**
159+
- Start with single files to test
160+
- Use glob patterns for batch processing
161+
- Preview changes before writing
162+
163+
**Quality assurance:**
164+
- Always review AI suggestions
165+
- Don't blindly accept all changes
166+
- Consider subject matter expertise needed
167+
- Test refined content for correctness
168+
169+
### Troubleshooting
45170

46-
* A valid `GITHUB_TOKEN` with Models scopes in your local `.env` file.
171+
**Missing token error:**
172+
Add `GITHUB_TOKEN` to `.env` with Models scopes.
47173

48-
## Future development ideas
174+
**API errors:**
175+
- Check token permissions
176+
- Verify rate limits
177+
- Check Models API status
49178

50-
* Add prompts to support all available editors.
51-
* Test prompts in Models UI and add evals to prevent regressions.
52-
* Enable running in CI.
53-
* Explore the new `llm` plugin for GitHub Models (see https://github.com/github/copilot-productivity/discussions/5937).
54-
* Add MCP for more comprehensive context.
55-
* Integrate with Copilot Edit mode in VS Code.
56-
* Add unit tests.
179+
**Poor refinement quality:**
180+
- Refine the prompt template
181+
- Add more examples
182+
- Test in Models UI first
183+
- Consider different model/parameters

‎src/app/README.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# App Router (`src/app`)
2+
3+
This directory contains the [Next.js App Router](https://nextjs.org/docs/app) implementation for GitHub Docs. It currently serves as the application shell, handling the root layout, global providers, and 404 error pages, while coexisting with the Pages Router implementation.
4+
5+
## Purpose & Scope
6+
7+
The `src/app` directory is the entry point for the Next.js App Router. Its primary responsibilities are:
8+
- Defining the root HTML structure and metadata.
9+
- Initializing global client-side context providers (Theme, Locale, Languages).
10+
- Handling global "Not Found" (404) scenarios.
11+
- Providing a bridge between the modern App Router architecture and the `MainContext` used by existing components.
12+
13+
We began this migration because we anticipate `@primer/react` will eventually drop support for the Pages Router. If that happens, we will be unable to upgrade `@primer/react`, effectively blocking us from receiving any future design system updates. Moving to the App Router prevents this and aligns us with the broader Next.js ecosystem.
14+
15+
## Architecture & Key Assets
16+
17+
### Directory Structure
18+
19+
- `layout.tsx`: The server-side Root Layout. It sets up the `<html>` and `<body>` tags, loads global styles, and defines metadata/viewport settings.
20+
- `client-layout.tsx`: A client component (`'use client'`) that wraps the application in necessary React Context providers. This allows server components to compose client-side logic for theming and state management.
21+
- `not-found.tsx`: The UI for 404 errors within the App Router.
22+
- `lib/`: Utilities for context adaptation and routing logic.
23+
- `app-router-context.ts`: Generates context data based on the current request path.
24+
- `main-context-adapter.ts`: Adapts App Router data structures to match the `MainContext` shape, ensuring backward compatibility for components.
25+
- `components/`: Client-side components specific to the App Router shell (e.g., wrappers for 404 pages, context providers).
26+
27+
### Key Concepts
28+
29+
- **Context Adaptation**: Since much of the codebase relies on a monolithic `MainContext`, this directory implements adapters to construct a compatible context object from App Router primitives. This allows us to reuse existing components without rewriting them immediately.
30+
- **Hybrid Routing**: The application currently operates in a hybrid mode. While `src/app` defines the outer shell, many specific routes and page rendering logic may still reside in the Pages Router (`src/pages`) or are being incrementally migrated.
31+
32+
## Setup & Usage
33+
34+
### Development
35+
36+
Standard Next.js App Router conventions apply. To add a new route using the App Router, create a folder with a `page.tsx` file inside `src/app`.
37+
38+
Useful documentation:
39+
- [Next.js App Router Documentation](https://nextjs.org/docs/app)
40+
- [Migrating from Pages to App Router](https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration)
41+
42+
### Testing
43+
44+
Tests for App Router logic should be placed alongside the components if applicable.
45+
46+
Tests that verify Next.js behavior (like 404 handling) can be found in `src/frame/tests/next.ts`.
47+
48+
## Data & External Dependencies
49+
50+
- **Data Sources**:
51+
- Consumes UI strings and language data from `src/data-directory` (via `getUIDataMerged`).
52+
- Uses `src/languages` for locale definitions.
53+
- **External Libraries**:
54+
- `@primer/react`: Used for the design system and theming provider.
55+
- `next`: The core framework.
56+
57+
## Cross-links & Ownership
58+
59+
- **Owner**: Docs Engineering
60+
- **Related Directories**:
61+
- `src/pages`: The Pages Router implementation.
62+
- `src/frame`: Server and middleware logic that interacts with routing.
63+
- `src/data-directory`: Source of static data used in layouts.
64+
65+
## Current State & Next Steps
66+
67+
- **Current State**: The App Router handles the root layout and 404s. It provides a compatibility layer for existing contexts.
68+
- **Next Steps**:
69+
- Migrate individual page routes from `src/pages` to `src/app`.
70+
- Refactor components to reduce dependency on the monolithic `MainContext`.
71+
- Improve data fetching patterns to use React Server Components (RSC) more effectively.

0 commit comments

Comments
 (0)