PR Review #5860
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: | |
| uses: docker/docker-agent-action/.github/workflows/review-pr.yml@e96a4bb40cac114f64358621e1d08346c8eadc8c # v2.0.1 | |
| # 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) | |
| Check for vendored or generated files before reviewing any changed content. | |
| Treat these paths as vendored/generated: | |
| - 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`) | |
| If all changed files are vendored/generated: | |
| - Leave at most one PR-level review comment. | |
| - Do not leave inline comments. | |
| - Do not review style, wording, markdown, command accuracy, links, or content quality inside those files. | |
| - Say only that the PR edits vendored/generated content, identify the affected path pattern, and direct the author to make the change upstream and sync it back. | |
| If a PR changes both vendored/generated files and hand-authored files: | |
| - Leave one comment for the vendored/generated file issue. | |
| - Review only the hand-authored files for the remaining priority issues below. | |
| - Do not leave style, wording, markdown, command accuracy, link, or content-quality comments on vendored/generated files. | |
| ### 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. |