mirror of
https://github.com/docker/docs.git
synced 2026-06-19 07:35:16 +00:00
David Karlsson
9740ff1294
Note in AGENTS.md and the PR review workflow that content/reference/api/ai-governance/api.yaml is a verbatim copy of the upstream OpenAPI spec, vendored from the private docker/governor-services repo via hack/sync-governance-api.sh, and should not be hand-edited. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
85 lines
4.0 KiB
YAML
85 lines
4.0 KiB
YAML
name: PR Review
|
|
on:
|
|
issue_comment:
|
|
types: [created]
|
|
workflow_run:
|
|
workflows: ["PR Review - Trigger"]
|
|
types: [completed]
|
|
|
|
permissions:
|
|
contents: read # Required at top-level to give `issue_comment` events access to the secrets below.
|
|
|
|
jobs:
|
|
review:
|
|
if: |
|
|
github.event_name == 'issue_comment' ||
|
|
github.event.workflow_run.conclusion == 'success'
|
|
uses: docker/cagent-action/.github/workflows/review-pr.yml@f208610469d69f20983cad64c577949a132caa33 # v1.5.3
|
|
# Scoped to the job so other jobs in this workflow aren't over-permissioned
|
|
permissions:
|
|
contents: read # Read repository files and PR diffs
|
|
pull-requests: write # Post review comments
|
|
issues: write # Create security incident issues if secrets detected
|
|
checks: write # (Optional) Show review progress as a check run
|
|
id-token: write # Required for OIDC authentication to AWS Secrets Manager
|
|
actions: read # Download artifacts from trigger workflow
|
|
with:
|
|
trigger-run-id: ${{ github.event_name == 'workflow_run' && format('{0}', github.event.workflow_run.id) || '' }}
|
|
add-prompt-files: STYLE.md,COMPONENTS.md
|
|
additional-prompt: |
|
|
## Documentation Review Focus
|
|
|
|
This is Docker's official documentation.
|
|
You are reviewing **DOCUMENTATION**, not code. Focus on documentation quality, not software bugs.
|
|
|
|
**Style guides are available via prompt files (STYLE.md, COMPONENTS.md)** - reference them when evaluating changes.
|
|
|
|
## Priority Issues
|
|
|
|
### 1. Vendored/Generated Content (CRITICAL - Auto-reject)
|
|
Flag if changes touch:
|
|
- Any file in `_vendor/` directory (vendored from upstream repos)
|
|
- Any YAML file in `data/*/*.yaml` subdirectories (CLI reference data generated from upstream)
|
|
- Examples: `data/engine-cli/*.yaml`, `data/buildx/*.yaml`, `data/scout-cli/*.yaml`
|
|
- Exception: root-level data/ files are manually maintained (allow edits)
|
|
- `content/reference/api/ai-governance/api.yaml` (verbatim copy of the upstream OpenAPI spec, vendored from the private docker/governor-services repo via `hack/sync-governance-api.sh`)
|
|
|
|
### 2. Missing Redirects When Removing/Moving Pages (HIGH)
|
|
When a PR removes or moves a page:
|
|
- Check if the PR adds an `aliases:` entry in the front matter of the target/replacement page
|
|
- Example: If `/old/path.md` is removed, there should be `aliases: ["/old/path/"]` in the new page
|
|
|
|
### 3. Markdown Formatting
|
|
- Poor markdown syntax (unclosed code blocks, broken lists, indentation issues, etc.)
|
|
|
|
### 4. AI-Generated Patterns (HIGH PRIORITY)
|
|
Flag AI-isms from STYLE.md:
|
|
- Hedge words: simply, just, easily, quickly, seamlessly
|
|
- Redundant phrases: "in order to", "allows you to"
|
|
- Meta-commentary: "it's worth noting that"
|
|
- Marketing speak: "robust", "powerful", "cutting-edge"
|
|
- Passive voice: "is used by" → "uses"
|
|
|
|
### 5. Scope Preservation
|
|
Does the change match existing document's length and tone?
|
|
Check STYLE.md "Scope preservation".
|
|
|
|
### 6. Content Accuracy
|
|
- Factually incorrect information (wrong commands, wrong API endpoints)
|
|
- Broken links or references
|
|
- Contradictory content
|
|
- Mismatched information (e.g., code example shows X but text says Y)
|
|
- Security issues in example code
|
|
|
|
### 7. Front Matter & Hugo Syntax
|
|
- Missing required fields: `title`, `description`, `keywords`
|
|
- Incorrect shortcode syntax (check COMPONENTS.md)
|
|
- Invalid component usage
|
|
|
|
## Severity
|
|
- **high**: Will mislead users or break things (incorrect commands, wrong APIs, security issues, editing vendored files, missing redirects)
|
|
- **medium**: Could confuse users or violates style guide (AI-isms, scope inflation, unclear instructions, markdown formatting)
|
|
- **low**: Minor suggestions (rarely report)
|
|
|
|
Most issues should be MEDIUM. HIGH is for critical problems only.
|