Skip to content

Commit 2a86d89

Browse files
Copilotncrmro
Copilot
and
ncrmro
committed
Add USAGE documentation for pr_docs_update job with examples
Co-authored-by: ncrmro <8276365+ncrmro@users.noreply.github.com>
1 parent c5da26d commit 2a86d89

2 files changed

Lines changed: 324 additions & 0 deletions

File tree

  • .deepwork/jobs/pr_docs_update
  • src/deepwork/standard_jobs/pr_docs_update

‎.deepwork/jobs/pr_docs_update/USAGE.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# PR Documentation Update Job - Example Usage
2+
3+
This document provides example usage scenarios for the `pr_docs_update` job.
4+
5+
## Overview
6+
7+
The `pr_docs_update` job automatically updates documentation by analyzing recently merged pull requests. It's designed to:
8+
- Keep AGENTS.md files up to date with code changes
9+
- Update copilot-specific instructions when relevant
10+
- Track processed PRs to avoid duplicates
11+
- Enable incremental processing across multiple runs
12+
13+
## Basic Usage
14+
15+
### First Run - Process Last 10 PRs
16+
17+
```bash
18+
# Run all steps to process the 10 most recent merged PRs
19+
/pr_docs_update.fetch_prs
20+
/pr_docs_update.analyze_prs
21+
/pr_docs_update.update_docs
22+
```
23+
24+
The job will:
25+
1. Fetch the 10 most recent merged PRs
26+
2. Filter out any already processed (from state file)
27+
3. Analyze each PR for documentation relevance
28+
4. Update appropriate documentation files
29+
5. Save processed PR numbers to state file
30+
31+
### Subsequent Runs - Process More PRs
32+
33+
```bash
34+
# Run with a higher count to go deeper into history
35+
# The state file automatically skips already-processed PRs
36+
/pr_docs_update.fetch_prs pr_count=20
37+
/pr_docs_update.analyze_prs
38+
/pr_docs_update.update_docs
39+
```
40+
41+
## Advanced Usage
42+
43+
### Custom State File Location
44+
45+
If you want to track state separately for different purposes:
46+
47+
```bash
48+
/pr_docs_update.fetch_prs state_file=".deepwork/pr_docs_copilot_state.json"
49+
/pr_docs_update.analyze_prs
50+
/pr_docs_update.update_docs state_file=".deepwork/pr_docs_copilot_state.json"
51+
```
52+
53+
### Reprocessing Specific PRs
54+
55+
To reprocess specific PRs, edit the state file:
56+
57+
```bash
58+
# View current state
59+
cat .deepwork/pr_docs_state.json
60+
61+
# Remove specific PR numbers you want to reprocess
62+
# Edit the file and remove those numbers from the "processed_prs" array
63+
```
64+
65+
### Processing Large Batches
66+
67+
For initial setup or catching up after a long time:
68+
69+
```bash
70+
# Process 50 PRs at once
71+
/pr_docs_update.fetch_prs pr_count=50
72+
/pr_docs_update.analyze_prs
73+
/pr_docs_update.update_docs
74+
```
75+
76+
## State File Structure
77+
78+
The state file (`.deepwork/pr_docs_state.json`) tracks processed PRs:
79+
80+
```json
81+
{
82+
"processed_prs": [123, 456, 789],
83+
"last_update": "2026-01-19T07:00:00Z",
84+
"total_processed": 3
85+
}
86+
```
87+
88+
## What Gets Updated?
89+
90+
### AGENTS.md Files
91+
92+
For general code changes that all agents should know about:
93+
- New jobs or workflows
94+
- Codebase structure changes
95+
- New conventions or patterns
96+
- Important context for working with the code
97+
98+
Located at: `.deepwork/jobs/[job_name]/AGENTS.md`
99+
100+
### Copilot-Specific Instructions
101+
102+
For changes specific to GitHub Copilot integration:
103+
- Copilot-specific features
104+
- Copilot workflow changes
105+
- Copilot tool usage patterns
106+
107+
Located at: `.github/copilot/` or similar copilot instruction locations
108+
109+
## Scheduling Recommendations
110+
111+
- **Weekly**: Run with default settings (10 PRs) to stay current
112+
- **After Major Releases**: Run with higher count (30-50 PRs)
113+
- **Initial Setup**: Process all recent PRs in batches
114+
115+
## Integration with Existing Workflows
116+
117+
This job can be combined with other DeepWork jobs:
118+
119+
```bash
120+
# Update docs from PRs, then commit the changes
121+
/pr_docs_update.fetch_prs
122+
/pr_docs_update.analyze_prs
123+
/pr_docs_update.update_docs
124+
125+
# Review and commit
126+
/commit.test
127+
/commit.lint
128+
/commit.commit_and_push
129+
```
130+
131+
## Troubleshooting
132+
133+
### No New PRs Found
134+
135+
If all fetched PRs have been processed:
136+
- Increase the `pr_count` parameter
137+
- Check the state file to see what's been processed
138+
- Consider clearing the state file to reprocess all PRs
139+
140+
### GitHub API Rate Limiting
141+
142+
If you hit rate limits:
143+
- Reduce the `pr_count` parameter
144+
- Wait for the rate limit to reset
145+
- Use authenticated GitHub API access if available
146+
147+
### Documentation Files Not Found
148+
149+
If expected documentation files don't exist:
150+
- The job will notify you about missing files
151+
- Create the necessary AGENTS.md or instruction files
152+
- Re-run the update step
153+
154+
## Example Output
155+
156+
After running the job, you'll have:
157+
158+
1. **pr_list.json**: List of fetched PRs (filtered by state)
159+
2. **pr_analysis.md**: Analysis of each PR with recommendations
160+
3. **updated_files_list.md**: Summary of what was updated
161+
4. **Updated documentation files**: AGENTS.md or copilot instructions with new content
162+
5. **Updated state file**: Tracking newly processed PRs

‎src/deepwork/standard_jobs/pr_docs_update/USAGE.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# PR Documentation Update Job - Example Usage
2+
3+
This document provides example usage scenarios for the `pr_docs_update` job.
4+
5+
## Overview
6+
7+
The `pr_docs_update` job automatically updates documentation by analyzing recently merged pull requests. It's designed to:
8+
- Keep AGENTS.md files up to date with code changes
9+
- Update copilot-specific instructions when relevant
10+
- Track processed PRs to avoid duplicates
11+
- Enable incremental processing across multiple runs
12+
13+
## Basic Usage
14+
15+
### First Run - Process Last 10 PRs
16+
17+
```bash
18+
# Run all steps to process the 10 most recent merged PRs
19+
/pr_docs_update.fetch_prs
20+
/pr_docs_update.analyze_prs
21+
/pr_docs_update.update_docs
22+
```
23+
24+
The job will:
25+
1. Fetch the 10 most recent merged PRs
26+
2. Filter out any already processed (from state file)
27+
3. Analyze each PR for documentation relevance
28+
4. Update appropriate documentation files
29+
5. Save processed PR numbers to state file
30+
31+
### Subsequent Runs - Process More PRs
32+
33+
```bash
34+
# Run with a higher count to go deeper into history
35+
# The state file automatically skips already-processed PRs
36+
/pr_docs_update.fetch_prs pr_count=20
37+
/pr_docs_update.analyze_prs
38+
/pr_docs_update.update_docs
39+
```
40+
41+
## Advanced Usage
42+
43+
### Custom State File Location
44+
45+
If you want to track state separately for different purposes:
46+
47+
```bash
48+
/pr_docs_update.fetch_prs state_file=".deepwork/pr_docs_copilot_state.json"
49+
/pr_docs_update.analyze_prs
50+
/pr_docs_update.update_docs state_file=".deepwork/pr_docs_copilot_state.json"
51+
```
52+
53+
### Reprocessing Specific PRs
54+
55+
To reprocess specific PRs, edit the state file:
56+
57+
```bash
58+
# View current state
59+
cat .deepwork/pr_docs_state.json
60+
61+
# Remove specific PR numbers you want to reprocess
62+
# Edit the file and remove those numbers from the "processed_prs" array
63+
```
64+
65+
### Processing Large Batches
66+
67+
For initial setup or catching up after a long time:
68+
69+
```bash
70+
# Process 50 PRs at once
71+
/pr_docs_update.fetch_prs pr_count=50
72+
/pr_docs_update.analyze_prs
73+
/pr_docs_update.update_docs
74+
```
75+
76+
## State File Structure
77+
78+
The state file (`.deepwork/pr_docs_state.json`) tracks processed PRs:
79+
80+
```json
81+
{
82+
"processed_prs": [123, 456, 789],
83+
"last_update": "2026-01-19T07:00:00Z",
84+
"total_processed": 3
85+
}
86+
```
87+
88+
## What Gets Updated?
89+
90+
### AGENTS.md Files
91+
92+
For general code changes that all agents should know about:
93+
- New jobs or workflows
94+
- Codebase structure changes
95+
- New conventions or patterns
96+
- Important context for working with the code
97+
98+
Located at: `.deepwork/jobs/[job_name]/AGENTS.md`
99+
100+
### Copilot-Specific Instructions
101+
102+
For changes specific to GitHub Copilot integration:
103+
- Copilot-specific features
104+
- Copilot workflow changes
105+
- Copilot tool usage patterns
106+
107+
Located at: `.github/copilot/` or similar copilot instruction locations
108+
109+
## Scheduling Recommendations
110+
111+
- **Weekly**: Run with default settings (10 PRs) to stay current
112+
- **After Major Releases**: Run with higher count (30-50 PRs)
113+
- **Initial Setup**: Process all recent PRs in batches
114+
115+
## Integration with Existing Workflows
116+
117+
This job can be combined with other DeepWork jobs:
118+
119+
```bash
120+
# Update docs from PRs, then commit the changes
121+
/pr_docs_update.fetch_prs
122+
/pr_docs_update.analyze_prs
123+
/pr_docs_update.update_docs
124+
125+
# Review and commit
126+
/commit.test
127+
/commit.lint
128+
/commit.commit_and_push
129+
```
130+
131+
## Troubleshooting
132+
133+
### No New PRs Found
134+
135+
If all fetched PRs have been processed:
136+
- Increase the `pr_count` parameter
137+
- Check the state file to see what's been processed
138+
- Consider clearing the state file to reprocess all PRs
139+
140+
### GitHub API Rate Limiting
141+
142+
If you hit rate limits:
143+
- Reduce the `pr_count` parameter
144+
- Wait for the rate limit to reset
145+
- Use authenticated GitHub API access if available
146+
147+
### Documentation Files Not Found
148+
149+
If expected documentation files don't exist:
150+
- The job will notify you about missing files
151+
- Create the necessary AGENTS.md or instruction files
152+
- Re-run the update step
153+
154+
## Example Output
155+
156+
After running the job, you'll have:
157+
158+
1. **pr_list.json**: List of fetched PRs (filtered by state)
159+
2. **pr_analysis.md**: Analysis of each PR with recommendations
160+
3. **updated_files_list.md**: Summary of what was updated
161+
4. **Updated documentation files**: AGENTS.md or copilot instructions with new content
162+
5. **Updated state file**: Tracking newly processed PRs

0 commit comments

Comments
 (0)