docs: Automatic Documentation Github Action using Droid (#45374)
Adds a multi-step agentic loop to github actions for opening a once-daily documentation PR that can be merged only be a Zedi Release Notes: - N/A --------- Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This commit is contained in:
morgankrey
55
.factory/prompts/docs-automation/phase2-explore.md
Normal file
55
.factory/prompts/docs-automation/phase2-explore.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# Phase 2: Explore Repository
|
||||
|
||||
You are analyzing a codebase to understand its structure before reviewing documentation impact.
|
||||
|
||||
## Objective
|
||||
Produce a structured overview of the repository to inform subsequent documentation analysis.
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Identify Primary Languages and Frameworks**
|
||||
- Scan for Cargo.toml, package.json, or other manifest files
|
||||
- Note the primary language(s) and key dependencies
|
||||
|
||||
2. **Map Documentation Structure**
|
||||
- This project uses **mdBook** (https://rust-lang.github.io/mdBook/)
|
||||
- Documentation is in `docs/src/`
|
||||
- Table of contents: `docs/src/SUMMARY.md` (mdBook format: https://rust-lang.github.io/mdBook/format/summary.html)
|
||||
- Style guide: `docs/.rules`
|
||||
- Agent guidelines: `docs/AGENTS.md`
|
||||
- Formatting: Prettier (config in `docs/.prettierrc`)
|
||||
|
||||
3. **Identify Build and Tooling**
|
||||
- Note build systems (cargo, npm, etc.)
|
||||
- Identify documentation tooling (mdbook, etc.)
|
||||
|
||||
4. **Output Format**
|
||||
Produce a JSON summary:
|
||||
|
||||
```json
|
||||
{
|
||||
"primary_language": "Rust",
|
||||
"frameworks": ["GPUI"],
|
||||
"documentation": {
|
||||
"system": "mdBook",
|
||||
"location": "docs/src/",
|
||||
"toc_file": "docs/src/SUMMARY.md",
|
||||
"toc_format": "https://rust-lang.github.io/mdBook/format/summary.html",
|
||||
"style_guide": "docs/.rules",
|
||||
"agent_guidelines": "docs/AGENTS.md",
|
||||
"formatter": "prettier",
|
||||
"formatter_config": "docs/.prettierrc",
|
||||
"custom_preprocessor": "docs_preprocessor (handles {#kb action::Name} syntax)"
|
||||
},
|
||||
"key_directories": {
|
||||
"source": "crates/",
|
||||
"docs": "docs/src/",
|
||||
"extensions": "extensions/"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Constraints
|
||||
- Read-only: Do not modify any files
|
||||
- Focus on structure, not content details
|
||||
- Complete within 2 minutes
|
||||
57
.factory/prompts/docs-automation/phase3-analyze.md
Normal file
57
.factory/prompts/docs-automation/phase3-analyze.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# Phase 3: Analyze Changes
|
||||
|
||||
You are analyzing code changes to understand their nature and scope.
|
||||
|
||||
## Objective
|
||||
Produce a clear, neutral summary of what changed in the codebase.
|
||||
|
||||
## Input
|
||||
You will receive:
|
||||
- List of changed files from the triggering commit/PR
|
||||
- Repository structure from Phase 2
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Categorize Changed Files**
|
||||
- Source code (which crates/modules)
|
||||
- Configuration
|
||||
- Tests
|
||||
- Documentation (already existing)
|
||||
- Other
|
||||
|
||||
2. **Analyze Each Change**
|
||||
- Review diffs for files likely to impact documentation
|
||||
- Focus on: public APIs, settings, keybindings, commands, user-visible behavior
|
||||
|
||||
3. **Identify What Did NOT Change**
|
||||
- Note stable interfaces or behaviors
|
||||
- Important for avoiding unnecessary documentation updates
|
||||
|
||||
4. **Output Format**
|
||||
Produce a markdown summary:
|
||||
|
||||
```markdown
|
||||
## Change Analysis
|
||||
|
||||
### Changed Files Summary
|
||||
| Category | Files | Impact Level |
|
||||
| --- | --- | --- |
|
||||
| Source - [crate] | file1.rs, file2.rs | High/Medium/Low |
|
||||
| Settings | settings.json | Medium |
|
||||
| Tests | test_*.rs | None |
|
||||
|
||||
### Behavioral Changes
|
||||
- **[Feature/Area]**: Description of what changed from user perspective
|
||||
- **[Feature/Area]**: Description...
|
||||
|
||||
### Unchanged Areas
|
||||
- [Area]: Confirmed no changes to [specific behavior]
|
||||
|
||||
### Files Requiring Deeper Review
|
||||
- `path/to/file.rs`: Reason for deeper review
|
||||
```
|
||||
|
||||
## Constraints
|
||||
- Read-only: Do not modify any files
|
||||
- Neutral tone: Describe what changed, not whether it's good/bad
|
||||
- Do not propose documentation changes yet
|
||||
76
.factory/prompts/docs-automation/phase4-plan.md
Normal file
76
.factory/prompts/docs-automation/phase4-plan.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# Phase 4: Plan Documentation Impact
|
||||
|
||||
You are determining whether and how documentation should be updated based on code changes.
|
||||
|
||||
## Objective
|
||||
Produce a structured documentation plan that will guide Phase 5 execution.
|
||||
|
||||
## Documentation System
|
||||
This is an **mdBook** site (https://rust-lang.github.io/mdBook/):
|
||||
- `docs/src/SUMMARY.md` defines book structure per https://rust-lang.github.io/mdBook/format/summary.html
|
||||
- If adding new pages, they MUST be added to SUMMARY.md
|
||||
- Use `{#kb action::ActionName}` syntax for keybindings (custom preprocessor expands these)
|
||||
- Prettier formatting (80 char width) will be applied automatically
|
||||
|
||||
## Input
|
||||
You will receive:
|
||||
- Change analysis from Phase 3
|
||||
- Repository structure from Phase 2
|
||||
- Documentation guidelines from `docs/AGENTS.md`
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Review AGENTS.md**
|
||||
- Load and apply all rules from `docs/AGENTS.md`
|
||||
- Respect scope boundaries (in-scope vs out-of-scope)
|
||||
|
||||
2. **Evaluate Documentation Impact**
|
||||
For each behavioral change from Phase 3:
|
||||
- Does existing documentation cover this area?
|
||||
- Is the documentation now inaccurate or incomplete?
|
||||
- Classify per AGENTS.md "Change Classification" section
|
||||
|
||||
3. **Identify Specific Updates**
|
||||
For each required update:
|
||||
- Exact file path
|
||||
- Specific section or heading
|
||||
- Type of change (update existing, add new, deprecate)
|
||||
- Description of the change
|
||||
|
||||
4. **Flag Uncertainty**
|
||||
Explicitly mark:
|
||||
- Assumptions you're making
|
||||
- Areas where human confirmation is needed
|
||||
- Ambiguous requirements
|
||||
|
||||
5. **Output Format**
|
||||
Use the exact format specified in `docs/AGENTS.md` Phase 4 section:
|
||||
|
||||
```markdown
|
||||
## Documentation Impact Assessment
|
||||
|
||||
### Summary
|
||||
Brief description of code changes analyzed.
|
||||
|
||||
### Documentation Updates Required: [Yes/No]
|
||||
|
||||
### Planned Changes
|
||||
|
||||
#### 1. [File Path]
|
||||
- **Section**: [Section name or "New section"]
|
||||
- **Change Type**: [Update/Add/Deprecate]
|
||||
- **Reason**: Why this change is needed
|
||||
- **Description**: What will be added/modified
|
||||
|
||||
### Uncertainty Flags
|
||||
- [ ] [Description of any assumptions or areas needing confirmation]
|
||||
|
||||
### No Changes Needed
|
||||
- [List files reviewed but not requiring updates, with brief reason]
|
||||
```
|
||||
|
||||
## Constraints
|
||||
- Read-only: Do not modify any files
|
||||
- Conservative: When uncertain, flag for human review rather than planning changes
|
||||
- Scoped: Only plan changes that trace directly to code changes from Phase 3
|
||||
- No scope expansion: Do not plan "improvements" unrelated to triggering changes
|
||||
67
.factory/prompts/docs-automation/phase5-apply.md
Normal file
67
.factory/prompts/docs-automation/phase5-apply.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# Phase 5: Apply Documentation Plan
|
||||
|
||||
You are executing a pre-approved documentation plan for an **mdBook** documentation site.
|
||||
|
||||
## Objective
|
||||
Implement exactly the changes specified in the documentation plan from Phase 4.
|
||||
|
||||
## Documentation System
|
||||
- **mdBook**: https://rust-lang.github.io/mdBook/
|
||||
- **SUMMARY.md**: Follows mdBook format (https://rust-lang.github.io/mdBook/format/summary.html)
|
||||
- **Prettier**: Will be run automatically after this phase (80 char line width)
|
||||
- **Custom preprocessor**: Use `{#kb action::ActionName}` for keybindings instead of hardcoding
|
||||
|
||||
## Input
|
||||
You will receive:
|
||||
- Documentation plan from Phase 4
|
||||
- Documentation guidelines from `docs/AGENTS.md`
|
||||
- Style rules from `docs/.rules`
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Validate Plan**
|
||||
- Confirm all planned files are within scope per AGENTS.md
|
||||
- Verify no out-of-scope files are targeted
|
||||
|
||||
2. **Execute Each Planned Change**
|
||||
For each item in "Planned Changes":
|
||||
- Navigate to the specified file
|
||||
- Locate the specified section
|
||||
- Apply the described change
|
||||
- Follow style rules from `docs/.rules`
|
||||
|
||||
3. **Style Compliance**
|
||||
Every edit must follow `docs/.rules`:
|
||||
- Second person, present tense
|
||||
- No hedging words ("simply", "just", "easily")
|
||||
- Proper keybinding format (`Cmd+Shift+P`)
|
||||
- Settings Editor first, JSON second
|
||||
- Correct terminology (folder not directory, etc.)
|
||||
|
||||
4. **Preserve Context**
|
||||
- Maintain surrounding content structure
|
||||
- Keep consistent heading levels
|
||||
- Preserve existing cross-references
|
||||
|
||||
## Constraints
|
||||
- Execute ONLY changes listed in the plan
|
||||
- Do not discover new documentation targets
|
||||
- Do not make stylistic improvements outside planned sections
|
||||
- Do not expand scope beyond what Phase 4 specified
|
||||
- If a planned change cannot be applied (file missing, section not found), skip and note it
|
||||
|
||||
## Output
|
||||
After applying changes, output a summary:
|
||||
|
||||
```markdown
|
||||
## Applied Changes
|
||||
|
||||
### Successfully Applied
|
||||
- `path/to/file.md`: [Brief description of change]
|
||||
|
||||
### Skipped (Could Not Apply)
|
||||
- `path/to/file.md`: [Reason - e.g., "Section not found"]
|
||||
|
||||
### Warnings
|
||||
- [Any issues encountered during application]
|
||||
```
|
||||
54
.factory/prompts/docs-automation/phase6-summarize.md
Normal file
54
.factory/prompts/docs-automation/phase6-summarize.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Phase 6: Summarize Changes
|
||||
|
||||
You are generating a summary of documentation updates for PR review.
|
||||
|
||||
## Objective
|
||||
Create a clear, reviewable summary of all documentation changes made.
|
||||
|
||||
## Input
|
||||
You will receive:
|
||||
- Applied changes report from Phase 5
|
||||
- Original change analysis from Phase 3
|
||||
- Git diff of documentation changes
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Gather Change Information**
|
||||
- List all modified documentation files
|
||||
- Identify the corresponding code changes that triggered each update
|
||||
|
||||
2. **Generate Summary**
|
||||
Use the format specified in `docs/AGENTS.md` Phase 6 section:
|
||||
|
||||
```markdown
|
||||
## Documentation Update Summary
|
||||
|
||||
### Changes Made
|
||||
| File | Change | Related Code |
|
||||
| --- | --- | --- |
|
||||
| docs/src/path.md | Brief description | PR #123 or commit SHA |
|
||||
|
||||
### Rationale
|
||||
Brief explanation of why these updates were made, linking back to the triggering code changes.
|
||||
|
||||
### Review Notes
|
||||
- Items reviewers should pay special attention to
|
||||
- Any uncertainty flags from Phase 4 that were addressed
|
||||
- Assumptions made during documentation
|
||||
```
|
||||
|
||||
3. **Add Context for Reviewers**
|
||||
- Highlight any changes that might be controversial
|
||||
- Note if any planned changes were skipped and why
|
||||
- Flag areas where reviewer expertise is especially needed
|
||||
|
||||
## Output Format
|
||||
The summary should be suitable for:
|
||||
- PR description body
|
||||
- Commit message (condensed version)
|
||||
- Team communication
|
||||
|
||||
## Constraints
|
||||
- Read-only (documentation changes already applied in Phase 5)
|
||||
- Factual: Describe what was done, not justify why it's good
|
||||
- Complete: Account for all changes, including skipped items
|
||||
67
.factory/prompts/docs-automation/phase7-commit.md
Normal file
67
.factory/prompts/docs-automation/phase7-commit.md
Normal file
@@ -0,0 +1,67 @@
|
||||
# Phase 7: Commit and Open PR
|
||||
|
||||
You are creating a git branch, committing documentation changes, and opening a PR.
|
||||
|
||||
## Objective
|
||||
Package documentation updates into a reviewable pull request.
|
||||
|
||||
## Input
|
||||
You will receive:
|
||||
- Summary from Phase 6
|
||||
- List of modified files
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Create Branch**
|
||||
```sh
|
||||
git checkout -b docs/auto-update-{date}
|
||||
```
|
||||
Use format: `docs/auto-update-YYYY-MM-DD` or `docs/auto-update-{short-sha}`
|
||||
|
||||
2. **Stage and Commit**
|
||||
- Stage only documentation files in `docs/src/`
|
||||
- Do not stage any other files
|
||||
|
||||
Commit message format:
|
||||
```
|
||||
docs: auto-update documentation for [brief description]
|
||||
|
||||
[Summary from Phase 6, condensed]
|
||||
|
||||
Triggered by: [commit SHA or PR reference]
|
||||
|
||||
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
|
||||
```
|
||||
|
||||
3. **Push Branch**
|
||||
```sh
|
||||
git push -u origin docs/auto-update-{date}
|
||||
```
|
||||
|
||||
4. **Create Pull Request**
|
||||
Use the Phase 6 summary as the PR body.
|
||||
|
||||
PR Title: `docs: [Brief description of documentation updates]`
|
||||
|
||||
Labels (if available): `documentation`, `automated`
|
||||
|
||||
Base branch: `main`
|
||||
|
||||
## Constraints
|
||||
- Do NOT auto-merge
|
||||
- Do NOT request specific reviewers (let CODEOWNERS handle it)
|
||||
- Do NOT modify files outside `docs/src/`
|
||||
- If no changes to commit, exit gracefully with message "No documentation changes to commit"
|
||||
|
||||
## Output
|
||||
```markdown
|
||||
## PR Created
|
||||
|
||||
- **Branch**: docs/auto-update-{date}
|
||||
- **PR URL**: https://github.com/zed-industries/zed/pull/XXXX
|
||||
- **Status**: Ready for review
|
||||
|
||||
### Commit
|
||||
- SHA: {commit-sha}
|
||||
- Files: {count} documentation files modified
|
||||
```
|
||||
256
.github/workflows/docs_automation.yml
vendored
Normal file
256
.github/workflows/docs_automation.yml
vendored
Normal file
@@ -0,0 +1,256 @@
|
||||
name: Documentation Automation
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- 'crates/**'
|
||||
- 'extensions/**'
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
pr_number:
|
||||
description: 'PR number to analyze (gets full PR diff)'
|
||||
required: false
|
||||
type: string
|
||||
trigger_sha:
|
||||
description: 'Commit SHA to analyze (ignored if pr_number is set)'
|
||||
required: false
|
||||
type: string
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: write
|
||||
|
||||
env:
|
||||
FACTORY_API_KEY: ${{ secrets.FACTORY_API_KEY }}
|
||||
DROID_MODEL: claude-opus-4-5
|
||||
|
||||
jobs:
|
||||
docs-automation:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Install Droid CLI
|
||||
run: |
|
||||
curl -fsSL https://cli.factory.ai/install.sh | bash
|
||||
echo "${HOME}/.factory/bin" >> "$GITHUB_PATH"
|
||||
|
||||
- name: Setup Node.js (for Prettier)
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
|
||||
- name: Install Prettier
|
||||
run: npm install -g prettier
|
||||
|
||||
- name: Get changed files
|
||||
id: changed
|
||||
run: |
|
||||
if [ -n "${{ inputs.pr_number }}" ]; then
|
||||
# Get full PR diff
|
||||
echo "Analyzing PR #${{ inputs.pr_number }}"
|
||||
echo "source=pr" >> "$GITHUB_OUTPUT"
|
||||
echo "ref=${{ inputs.pr_number }}" >> "$GITHUB_OUTPUT"
|
||||
gh pr diff "${{ inputs.pr_number }}" --name-only > /tmp/changed_files.txt
|
||||
elif [ -n "${{ inputs.trigger_sha }}" ]; then
|
||||
# Get single commit diff
|
||||
SHA="${{ inputs.trigger_sha }}"
|
||||
echo "Analyzing commit $SHA"
|
||||
echo "source=commit" >> "$GITHUB_OUTPUT"
|
||||
echo "ref=$SHA" >> "$GITHUB_OUTPUT"
|
||||
git diff --name-only "${SHA}^" "$SHA" > /tmp/changed_files.txt
|
||||
else
|
||||
# Default to current commit
|
||||
SHA="${{ github.sha }}"
|
||||
echo "Analyzing commit $SHA"
|
||||
echo "source=commit" >> "$GITHUB_OUTPUT"
|
||||
echo "ref=$SHA" >> "$GITHUB_OUTPUT"
|
||||
git diff --name-only "${SHA}^" "$SHA" > /tmp/changed_files.txt || git diff --name-only HEAD~1 HEAD > /tmp/changed_files.txt
|
||||
fi
|
||||
|
||||
echo "Changed files:"
|
||||
cat /tmp/changed_files.txt
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
|
||||
# Phase 0: Guardrails are loaded via AGENTS.md in each phase
|
||||
|
||||
# Phase 2: Explore Repository (Read-Only)
|
||||
- name: "Phase 2: Explore Repository"
|
||||
id: phase2
|
||||
run: |
|
||||
droid exec \
|
||||
--model "$DROID_MODEL" \
|
||||
--autonomy read-only \
|
||||
--prompt-file .factory/prompts/docs-automation/phase2-explore.md \
|
||||
--output /tmp/phase2-output.json \
|
||||
--format json
|
||||
echo "Repository exploration complete"
|
||||
cat /tmp/phase2-output.json
|
||||
|
||||
# Phase 3: Analyze Changes (Read-Only)
|
||||
- name: "Phase 3: Analyze Changes"
|
||||
id: phase3
|
||||
run: |
|
||||
CHANGED_FILES=$(tr '\n' ' ' < /tmp/changed_files.txt)
|
||||
droid exec \
|
||||
--model "$DROID_MODEL" \
|
||||
--autonomy read-only \
|
||||
--prompt-file .factory/prompts/docs-automation/phase3-analyze.md \
|
||||
--context "Changed files: $CHANGED_FILES" \
|
||||
--context-file /tmp/phase2-output.json \
|
||||
--output /tmp/phase3-output.md \
|
||||
--format markdown
|
||||
echo "Change analysis complete"
|
||||
cat /tmp/phase3-output.md
|
||||
|
||||
# Phase 4: Plan Documentation Impact (Read-Only)
|
||||
- name: "Phase 4: Plan Documentation Impact"
|
||||
id: phase4
|
||||
run: |
|
||||
droid exec \
|
||||
--model "$DROID_MODEL" \
|
||||
--autonomy read-only \
|
||||
--prompt-file .factory/prompts/docs-automation/phase4-plan.md \
|
||||
--context-file /tmp/phase3-output.md \
|
||||
--context-file docs/AGENTS.md \
|
||||
--output /tmp/phase4-plan.md \
|
||||
--format markdown
|
||||
echo "Documentation plan complete"
|
||||
cat /tmp/phase4-plan.md
|
||||
|
||||
# Check if updates are required
|
||||
if grep -q "Documentation Updates Required: No" /tmp/phase4-plan.md; then
|
||||
echo "updates_required=false" >> "$GITHUB_OUTPUT"
|
||||
else
|
||||
echo "updates_required=true" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
|
||||
# Phase 5: Apply Plan (Write-Enabled)
|
||||
- name: "Phase 5: Apply Documentation Plan"
|
||||
id: phase5
|
||||
if: steps.phase4.outputs.updates_required == 'true'
|
||||
run: |
|
||||
droid exec \
|
||||
--model "$DROID_MODEL" \
|
||||
--autonomy medium \
|
||||
--prompt-file .factory/prompts/docs-automation/phase5-apply.md \
|
||||
--context-file /tmp/phase4-plan.md \
|
||||
--context-file docs/AGENTS.md \
|
||||
--context-file docs/.rules \
|
||||
--output /tmp/phase5-report.md \
|
||||
--format markdown
|
||||
echo "Documentation updates applied"
|
||||
cat /tmp/phase5-report.md
|
||||
|
||||
# Phase 5b: Format with Prettier
|
||||
- name: "Phase 5b: Format with Prettier"
|
||||
id: phase5b
|
||||
if: steps.phase4.outputs.updates_required == 'true'
|
||||
run: |
|
||||
echo "Formatting documentation with Prettier..."
|
||||
cd docs && prettier --write src/
|
||||
|
||||
echo "Verifying Prettier formatting passes..."
|
||||
cd docs && prettier --check src/
|
||||
|
||||
echo "Prettier formatting complete"
|
||||
|
||||
# Phase 6: Summarize Changes
|
||||
- name: "Phase 6: Summarize Changes"
|
||||
id: phase6
|
||||
if: steps.phase4.outputs.updates_required == 'true'
|
||||
run: |
|
||||
# Get git diff of docs
|
||||
git diff docs/src/ > /tmp/docs-diff.txt || true
|
||||
|
||||
droid exec \
|
||||
--model "$DROID_MODEL" \
|
||||
--autonomy read-only \
|
||||
--prompt-file .factory/prompts/docs-automation/phase6-summarize.md \
|
||||
--context-file /tmp/phase5-report.md \
|
||||
--context-file /tmp/phase3-output.md \
|
||||
--context "Trigger SHA: ${{ steps.changed.outputs.sha }}" \
|
||||
--output /tmp/phase6-summary.md \
|
||||
--format markdown
|
||||
echo "Summary generated"
|
||||
cat /tmp/phase6-summary.md
|
||||
|
||||
# Phase 7: Commit and Open PR
|
||||
- name: "Phase 7: Create PR"
|
||||
id: phase7
|
||||
if: steps.phase4.outputs.updates_required == 'true'
|
||||
run: |
|
||||
# Check if there are actual changes
|
||||
if git diff --quiet docs/src/; then
|
||||
echo "No documentation changes detected"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Configure git
|
||||
git config user.name "factory-droid[bot]"
|
||||
git config user.email "138933559+factory-droid[bot]@users.noreply.github.com"
|
||||
|
||||
# Daily batch branch - one branch per day, multiple commits accumulate
|
||||
BRANCH_NAME="docs/auto-update-$(date +%Y-%m-%d)"
|
||||
|
||||
# Check if branch already exists on remote
|
||||
if git ls-remote --exit-code --heads origin "$BRANCH_NAME" > /dev/null 2>&1; then
|
||||
echo "Branch $BRANCH_NAME exists, checking out and updating..."
|
||||
git fetch origin "$BRANCH_NAME"
|
||||
git checkout -B "$BRANCH_NAME" "origin/$BRANCH_NAME"
|
||||
else
|
||||
echo "Creating new branch $BRANCH_NAME..."
|
||||
git checkout -b "$BRANCH_NAME"
|
||||
fi
|
||||
|
||||
# Stage and commit
|
||||
git add docs/src/
|
||||
SUMMARY=$(head -50 < /tmp/phase6-summary.md)
|
||||
git commit -m "docs: auto-update documentation
|
||||
|
||||
${SUMMARY}
|
||||
|
||||
Triggered by: ${{ steps.changed.outputs.source }} ${{ steps.changed.outputs.ref }}
|
||||
|
||||
Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>"
|
||||
|
||||
# Push
|
||||
git push -u origin "$BRANCH_NAME"
|
||||
|
||||
# Check if PR already exists for this branch
|
||||
EXISTING_PR=$(gh pr list --head "$BRANCH_NAME" --json number --jq '.[0].number' || echo "")
|
||||
|
||||
if [ -n "$EXISTING_PR" ]; then
|
||||
echo "PR #$EXISTING_PR already exists for branch $BRANCH_NAME, updated with new commit"
|
||||
else
|
||||
# Create new PR
|
||||
gh pr create \
|
||||
--title "docs: automated documentation update ($(date +%Y-%m-%d))" \
|
||||
--body-file /tmp/phase6-summary.md \
|
||||
--base main || true
|
||||
echo "PR created on branch: $BRANCH_NAME"
|
||||
fi
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
|
||||
# Summary output
|
||||
- name: "Summary"
|
||||
if: always()
|
||||
run: |
|
||||
echo "## Documentation Automation Summary" >> "$GITHUB_STEP_SUMMARY"
|
||||
echo "" >> "$GITHUB_STEP_SUMMARY"
|
||||
|
||||
if [ "${{ steps.phase4.outputs.updates_required }}" == "false" ]; then
|
||||
echo "No documentation updates required for this change." >> "$GITHUB_STEP_SUMMARY"
|
||||
elif [ -f /tmp/phase6-summary.md ]; then
|
||||
cat /tmp/phase6-summary.md >> "$GITHUB_STEP_SUMMARY"
|
||||
else
|
||||
echo "Workflow completed. Check individual phase outputs for details." >> "$GITHUB_STEP_SUMMARY"
|
||||
fi
|
||||
353
docs/AGENTS.md
Normal file
353
docs/AGENTS.md
Normal file
@@ -0,0 +1,353 @@
|
||||
# Documentation Automation Agent Guidelines
|
||||
|
||||
This file governs automated documentation updates triggered by code changes. All automation phases must comply with these rules.
|
||||
|
||||
## Documentation System
|
||||
|
||||
This documentation uses **mdBook** (https://rust-lang.github.io/mdBook/).
|
||||
|
||||
### Key Files
|
||||
|
||||
- **`docs/src/SUMMARY.md`**: Table of contents following mdBook format (https://rust-lang.github.io/mdBook/format/summary.html)
|
||||
- **`docs/book.toml`**: mdBook configuration
|
||||
- **`docs/.prettierrc`**: Prettier config (80 char line width)
|
||||
|
||||
### SUMMARY.md Format
|
||||
|
||||
The `SUMMARY.md` file defines the book structure. Format rules:
|
||||
|
||||
- Chapter titles are links: `[Title](./path/to/file.md)`
|
||||
- Nesting via indentation (2 spaces per level)
|
||||
- Separators: `---` for horizontal rules between sections
|
||||
- Draft chapters: `[Title]()` (empty parens, not yet written)
|
||||
|
||||
Example:
|
||||
|
||||
```markdown
|
||||
# Section Title
|
||||
|
||||
- [Chapter](./chapter.md)
|
||||
- [Nested Chapter](./nested.md)
|
||||
|
||||
---
|
||||
|
||||
# Another Section
|
||||
```
|
||||
|
||||
### Custom Preprocessor
|
||||
|
||||
The docs use a custom preprocessor (`docs_preprocessor`) that expands special commands:
|
||||
|
||||
| Syntax | Purpose | Example |
|
||||
| ----------------------------- | ------------------------------------- | ------------------------------- |
|
||||
| `{#kb action::ActionName}` | Keybinding for action | `{#kb agent::ToggleFocus}` |
|
||||
| `{#action agent::ActionName}` | Action reference (renders as command) | `{#action agent::OpenSettings}` |
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Always use preprocessor syntax for keybindings instead of hardcoding
|
||||
- Action names use `snake_case` in the namespace, `PascalCase` for the action
|
||||
- Common namespaces: `agent::`, `editor::`, `assistant::`, `vim::`
|
||||
|
||||
### Formatting Requirements
|
||||
|
||||
All documentation must pass **Prettier** formatting:
|
||||
|
||||
```sh
|
||||
cd docs && npx prettier --check src/
|
||||
```
|
||||
|
||||
Before any documentation change is considered complete:
|
||||
|
||||
1. Run Prettier to format: `cd docs && npx prettier --write src/`
|
||||
2. Verify it passes: `cd docs && npx prettier --check src/`
|
||||
|
||||
Prettier config: 80 character line width (`docs/.prettierrc`)
|
||||
|
||||
### Section Anchors
|
||||
|
||||
Use `{#anchor-id}` syntax for linkable section headers:
|
||||
|
||||
```markdown
|
||||
## Getting Started {#getting-started}
|
||||
|
||||
### Custom Models {#anthropic-custom-models}
|
||||
```
|
||||
|
||||
Anchor IDs should be:
|
||||
|
||||
- Lowercase with hyphens
|
||||
- Unique within the page
|
||||
- Descriptive (can include parent context like `anthropic-custom-models`)
|
||||
|
||||
### Code Block Annotations
|
||||
|
||||
Use annotations after the language identifier to indicate file context:
|
||||
|
||||
```markdown
|
||||
\`\`\`json [settings]
|
||||
{
|
||||
"agent": { ... }
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
\`\`\`json [keymap]
|
||||
[
|
||||
{ "bindings": { ... } }
|
||||
]
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
Valid annotations: `[settings]` (for settings.json), `[keymap]` (for keymap.json)
|
||||
|
||||
### Blockquote Formatting
|
||||
|
||||
Use bold labels for callouts:
|
||||
|
||||
```markdown
|
||||
> **Note:** Important information the user should know.
|
||||
|
||||
> **Tip:** Helpful advice that saves time or improves workflow.
|
||||
|
||||
> **Warn:** Caution about potential issues or gotchas.
|
||||
```
|
||||
|
||||
### Image References
|
||||
|
||||
Images are hosted externally. Reference format:
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
### Cross-Linking
|
||||
|
||||
- Relative links for same-directory: `[Agent Panel](./agent-panel.md)`
|
||||
- With anchors: `[Custom Models](./llm-providers.md#anthropic-custom-models)`
|
||||
- Parent directory: `[Telemetry](../telemetry.md)`
|
||||
|
||||
## Scope
|
||||
|
||||
### In-Scope Documentation
|
||||
|
||||
- All Markdown files in `docs/src/`
|
||||
- `docs/src/SUMMARY.md` (mdBook table of contents)
|
||||
- Language-specific docs in `docs/src/languages/`
|
||||
- Feature docs (AI, extensions, configuration, etc.)
|
||||
|
||||
### Out-of-Scope (Do Not Modify)
|
||||
|
||||
- `CHANGELOG.md`, `CONTRIBUTING.md`, `README.md` at repo root
|
||||
- Inline code comments and rustdoc
|
||||
- `CLAUDE.md`, `GEMINI.md`, or other AI instruction files
|
||||
- Build configuration (`book.toml`, theme files, `docs_preprocessor`)
|
||||
- Any file outside `docs/src/`
|
||||
|
||||
## Page Structure Patterns
|
||||
|
||||
### Standard Page Layout
|
||||
|
||||
Most documentation pages follow this structure:
|
||||
|
||||
1. **Title** (H1) - Single sentence or phrase
|
||||
2. **Overview/Introduction** - 1-3 paragraphs explaining what this is
|
||||
3. **Getting Started** `{#getting-started}` - Prerequisites and first steps
|
||||
4. **Main Content** - Feature details, organized by topic
|
||||
5. **Advanced/Configuration** - Power user options
|
||||
6. **See Also** (optional) - Related documentation links
|
||||
|
||||
### Settings Documentation Pattern
|
||||
|
||||
When documenting settings:
|
||||
|
||||
1. Show the Settings Editor (UI) approach first
|
||||
2. Then show JSON as "Or add this to your settings.json:"
|
||||
3. Always show complete, valid JSON with surrounding structure:
|
||||
|
||||
```json [settings]
|
||||
{
|
||||
"agent": {
|
||||
"default_model": {
|
||||
"provider": "anthropic",
|
||||
"model": "claude-sonnet-4"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Provider/Feature Documentation Pattern
|
||||
|
||||
For each provider or distinct feature:
|
||||
|
||||
1. H3 heading with anchor: `### Provider Name {#provider-name}`
|
||||
2. Brief description (1-2 sentences)
|
||||
3. Setup steps (numbered list)
|
||||
4. Configuration example (JSON code block)
|
||||
5. Custom models section if applicable: `#### Custom Models {#provider-custom-models}`
|
||||
|
||||
## Style Rules
|
||||
|
||||
Inherit all conventions from `docs/.rules`. Key points:
|
||||
|
||||
### Voice
|
||||
|
||||
- Second person ("you"), present tense
|
||||
- Direct and concise—no hedging ("simply", "just", "easily")
|
||||
- Honest about limitations; no promotional language
|
||||
|
||||
### Formatting
|
||||
|
||||
- Keybindings: backticks with `+` for simultaneous keys (`Cmd+Shift+P`)
|
||||
- Show both macOS and Linux/Windows variants when they differ
|
||||
- Use `sh` code blocks for terminal commands
|
||||
- Settings: show Settings Editor UI first, JSON as secondary
|
||||
|
||||
### Terminology
|
||||
|
||||
| Use | Instead of |
|
||||
| --------------- | -------------------------------------- |
|
||||
| folder | directory |
|
||||
| project | workspace |
|
||||
| Settings Editor | settings UI |
|
||||
| command palette | command bar |
|
||||
| panel | sidebar (be specific: "Project Panel") |
|
||||
|
||||
## Zed-Specific Conventions
|
||||
|
||||
### Recognized Rules Files
|
||||
|
||||
When documenting rules/instructions for AI, note that Zed recognizes these files (in priority order):
|
||||
|
||||
- `.rules`
|
||||
- `.cursorrules`
|
||||
- `.windsurfrules`
|
||||
- `.clinerules`
|
||||
- `.github/copilot-instructions.md`
|
||||
- `AGENT.md`
|
||||
- `AGENTS.md`
|
||||
- `CLAUDE.md`
|
||||
- `GEMINI.md`
|
||||
|
||||
### Settings File Locations
|
||||
|
||||
- macOS: `~/.config/zed/settings.json`
|
||||
- Linux: `~/.config/zed/settings.json`
|
||||
- Windows: `%AppData%\Zed\settings.json`
|
||||
|
||||
### Keymap File Locations
|
||||
|
||||
- macOS: `~/.config/zed/keymap.json`
|
||||
- Linux: `~/.config/zed/keymap.json`
|
||||
- Windows: `%AppData%\Zed\keymap.json`
|
||||
|
||||
## Safety Constraints
|
||||
|
||||
### Must Not
|
||||
|
||||
- Delete existing documentation files
|
||||
- Remove sections documenting existing functionality
|
||||
- Change URLs or anchor links without verifying references
|
||||
- Modify `SUMMARY.md` structure without corresponding content
|
||||
- Add speculative documentation for unreleased features
|
||||
- Include internal implementation details not relevant to users
|
||||
|
||||
### Must
|
||||
|
||||
- Preserve existing structure when updating content
|
||||
- Maintain backward compatibility of documented settings/commands
|
||||
- Flag uncertainty explicitly rather than guessing
|
||||
- Link to related documentation when adding new sections
|
||||
|
||||
## Change Classification
|
||||
|
||||
### Requires Documentation Update
|
||||
|
||||
- New user-facing features or commands
|
||||
- Changed keybindings or default behaviors
|
||||
- Modified settings schema or options
|
||||
- Deprecated or removed functionality
|
||||
- API changes affecting extensions
|
||||
|
||||
### Does Not Require Documentation Update
|
||||
|
||||
- Internal refactoring without behavioral changes
|
||||
- Performance optimizations (unless user-visible)
|
||||
- Bug fixes that restore documented behavior
|
||||
- Test changes
|
||||
- CI/CD changes
|
||||
|
||||
## Output Format
|
||||
|
||||
### Phase 4 Documentation Plan
|
||||
|
||||
When generating a documentation plan, use this structure:
|
||||
|
||||
```markdown
|
||||
## Documentation Impact Assessment
|
||||
|
||||
### Summary
|
||||
|
||||
Brief description of code changes analyzed.
|
||||
|
||||
### Documentation Updates Required: [Yes/No]
|
||||
|
||||
### Planned Changes
|
||||
|
||||
#### 1. [File Path]
|
||||
|
||||
- **Section**: [Section name or "New section"]
|
||||
- **Change Type**: [Update/Add/Deprecate]
|
||||
- **Reason**: Why this change is needed
|
||||
- **Description**: What will be added/modified
|
||||
|
||||
#### 2. [File Path]
|
||||
|
||||
...
|
||||
|
||||
### Uncertainty Flags
|
||||
|
||||
- [ ] [Description of any assumptions or areas needing confirmation]
|
||||
|
||||
### No Changes Needed
|
||||
|
||||
- [List files reviewed but not requiring updates, with brief reason]
|
||||
```
|
||||
|
||||
### Phase 6 Summary Format
|
||||
|
||||
```markdown
|
||||
## Documentation Update Summary
|
||||
|
||||
### Changes Made
|
||||
|
||||
| File | Change | Related Code |
|
||||
| -------------- | ----------------- | ----------------- |
|
||||
| path/to/doc.md | Brief description | link to PR/commit |
|
||||
|
||||
### Rationale
|
||||
|
||||
Brief explanation of why these updates were made.
|
||||
|
||||
### Review Notes
|
||||
|
||||
Any items reviewers should pay special attention to.
|
||||
```
|
||||
|
||||
## Behavioral Guidelines
|
||||
|
||||
### Conservative by Default
|
||||
|
||||
- When uncertain whether to document something, flag it for human review
|
||||
- Prefer smaller, focused updates over broad rewrites
|
||||
- Do not "improve" documentation unrelated to the triggering code change
|
||||
|
||||
### Traceability
|
||||
|
||||
- Every documentation change should trace to a specific code change
|
||||
- Include references to relevant commits, PRs, or issues in summaries
|
||||
|
||||
### Incremental Updates
|
||||
|
||||
- Update existing sections rather than creating parallel documentation
|
||||
- Maintain consistency with surrounding content
|
||||
- Follow the established patterns in each documentation area
|
||||
Reference in New Issue
Block a user