diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 4b2ce3e3199b..e57ca0a4da6b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -4,7 +4,7 @@ If directory-specific AGENTS.md files exist, prefer the nearest one. ## PR Reviews -These rules **must** be followed during all pull request reviews: +**Pull Request Review Criteria**: - Use **GitHub Review suggestions** (`suggestion` blocks) whenever possible so changes can be applied with one click. - Always enforce `STYLE-GUIDE.md`. If not covered there, fall back to the [Google Developer Documentation Style Guide](https://developers.google.com/style). @@ -14,9 +14,9 @@ These rules **must** be followed during all pull request reviews: - Validate that **content is accurate and current** (commands, APIs, terminology). - Ensure **all new files end with a newline**. - **If files are moved, renamed, or deleted**: - - Ensure that all references to them are updated accordingly. - - Ensure that redirects are created for any moved or renamed files, if applicable. -- **Documentation**: Serve the role of a professional technical writer. Review for: + - Confirm that moved or renamed files have appropriate aliases added to the frontmatter to avoid broken links. + - Confirm that deleted files have a redirect created, if applicable. +- When reviewing **Documentation**: Serve the role of a professional technical writer. Review for: - Clarity and conciseness. - Logical flow and structure. - No jargon unless defined. @@ -26,7 +26,7 @@ These rules **must** be followed during all pull request reviews: - Avoid unnecessary filler words or sentences. - Be specific and provide examples. - Use consistent terminology. -- **Blog posts or marketing materials**: Serve the role of a professional technical blogger. Review for: +- When reviewing **Blog posts or marketing materials**: Serve the role of a professional technical blogger. Review for: - Clear, engaging titles. - Strong opening that hooks the reader. - Clear structure with headings and subheadings. diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index a937c44410eb..c066e991efd3 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -12,11 +12,8 @@ on: jobs: claude-review: - # Optional: Filter by PR author - # if: | - # github.event.pull_request.user.login == 'external-contributor' || - # github.event.pull_request.user.login == 'new-developer' || - # github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' + # Skip automated PRs from pulumi-bot + if: github.event.pull_request.user.login != 'pulumi-bot' runs-on: ubuntu-latest permissions: @@ -43,11 +40,11 @@ jobs: Use the repository's CLAUDE.md, AGENTS.md, and STYLE-GUIDE.md for guidance on style and conventions. - Be constructive and helpful in your feedback. + Be constructive and helpful in your feedback, but don't overdo the praise. Be concise. Always provide relevant line numbers for any issues you identify. - These rules **must** be followed during all pull request reviews: + **Pull Request Review Criteria**: - Always enforce `STYLE-GUIDE.md`. If not covered there, fall back to the [Google Developer Documentation Style Guide](https://developers.google.com/style). - Check **spelling and grammar** in all files. @@ -56,9 +53,9 @@ jobs: - Validate that **content is accurate and current** (commands, APIs, terminology). - Ensure **all new files end with a newline**. - **If files are moved, renamed, or deleted**: - - Ensure that all references to them are updated accordingly. - - Ensure that redirects are created for any moved or renamed files, if applicable. - - **Documentation**: Serve the role of a professional technical writer. Review for: + - Confirm that moved or renamed files have appropriate aliases added to the frontmatter to avoid broken links. + - Confirm that deleted files have a redirect created, if applicable. + - When reviewing **Documentation**: Serve the role of a professional technical writer. Review for: - Clarity and conciseness. - Logical flow and structure. - No jargon unless defined. @@ -68,7 +65,7 @@ jobs: - Avoid unnecessary filler words or sentences. - Be specific and provide examples. - Use consistent terminology. - - **Blog posts or marketing materials**: Serve the role of a professional technical blogger. Review for: + - When reviewing **Blog posts or marketing materials**: Serve the role of a professional technical blogger. Review for: - Clear, engaging titles. - Strong opening that hooks the reader. - Clear structure with headings and subheadings. diff --git a/AGENTS.md b/AGENTS.md index b488212ab750..f5d12677572f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,7 +48,7 @@ Do not substitute other tools or commands. ## Code & Content Rules -- **Markdown**: Semantic line breaks (one line per sentence/phrase). +- **Markdown**: Standard paragraph formatting. - **Headings**: - H1 = Title Case - H2+ = Sentence case diff --git a/STYLE-GUIDE.md b/STYLE-GUIDE.md index da3aaec1bfea..98c6a5f558e3 100644 --- a/STYLE-GUIDE.md +++ b/STYLE-GUIDE.md @@ -29,6 +29,8 @@ Pulumi strives to use language that is clear, inclusive, and respectful. - H2 and deeper: **Sentence case**. - Only increment one heading level at a time (no skipping levels). - Use capitalization only for proper nouns. For example, use “stack” not “Stack.” +- Do not end headings with punctuation. +- Headings should be surrounded by blank lines. --- @@ -62,7 +64,8 @@ This is a useful suggestion. ## Paragraphs and Line Breaks -- Use **semantic line breaks**: start a new line for each sentence or phrase. +- Separate paragraphs with a blank line. +- Do not use line breaks within paragraphs. Let text wrap naturally. - Keep paragraphs short (ideally ≤3 sentences). ---