mirror of
https://github.com/docker/docs.git
synced 2026-06-19 07:35:16 +00:00
David Karlsson
20a3d5a774
The PR-review bot's prompt instructed it to flag lines over 80 characters, but no such rule exists in the repo (markdownlint MD013 is disabled and STYLE.md never mentions it). Remove that instruction from pr-review.yml. Also clarify the STYLE.md word list so "turn on/off" applies to UI toggles while "enable/disable" stays acceptable in general prose, matching STYLE.md's own example. This stops the bot from flagging every "enable" as a violation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
84 lines
3.8 KiB
YAML
84 lines
3.8 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)
|
|
|
|
### 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.
|