PR Review #3520
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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) | |
| ### 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.) | |
| - Line wrapping over 80 characters (except links, code blocks, tables) | |
| ### 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. |