[PWCI] "[RFC] doc: add AGENTS.md for AI-powered code review tools"#612
Open
[PWCI] "[RFC] doc: add AGENTS.md for AI-powered code review tools"#612
Conversation
Add a structured reference document that enables AI code review tools to validate DPDK contributions against project standards. This document consolidates requirements from multiple sources into a machine-readable format optimized for automated validation workflows. The AGENTS.md file synthesizes guidelines from: - DPDK Contributing Code documentation (patches.rst) - DPDK Coding Style guidelines (coding_style.rst) - Linux kernel patch submission process (submitting-patches.rst) - SPDX License Identifier specification (spdx.org) Key sections include: - SPDX license identifier requirements - Commit message format and tag ordering - C coding style rules and naming conventions - Patch validation checklists with severity levels - Meson build file style requirements The document provides actionable checklists and concrete examples to support integration with CI/CD pipelines and automated review systems. Severity levels (error/warning/info) help tools prioritize feedback appropriately. This supports the broader goal of maintaining code quality and consistency as the project scales, while reducing manual review burden for maintainers on mechanical style issues. References: - https://doc.dpdk.org/guides/contributing/patches.html - https://doc.dpdk.org/guides/contributing/coding_style.html - https://www.kernel.org/doc/html/latest/process/submitting-patches.html - https://spdx.org/licenses/ Signed-off-by: Stephen Hemminger <stephen@networkplumber.org> Signed-off-by: 0-day Robot <robot@bytheb.org>
Reviewer's GuideAdds a new AGENTS.md documentation file that codifies DPDK-specific guidelines and checklists for AI-powered code review tools, covering licensing, commit messages, C/Meson/Python style, testing, ABI, and review process severity levels. Flow diagram for AI patch validation checklistflowchart TD
A[Start_patch_review] --> B[Check_commit_message]
B --> B1[Validate_subject_length_and_lowercase]
B1 --> B2[Verify_component_prefix_and_imperative_mood]
B2 --> B3[Check_no_trailing_period]
B3 --> B4[Ensure_body_wrapped_at_72_chars]
B4 --> B5[Confirm_Signed_off_by_present]
B5 --> B6[If_bug_fix_check_Fixes_tag_and_order]
B6 --> C[Check_license_headers]
C --> C1[SPDX_identifier_on_first_line]
C1 --> C2[License_matches_file_type]
C2 --> C3[Blank_line_after_license_header]
C3 --> D[Check_code_style]
D --> D1[Line_lengths_and_tabs]
D1 --> D2[No_trailing_whitespace]
D2 --> D3[Includes_order_and_header_guards]
D3 --> D4[Naming_conventions_and_prohibited_terms]
D4 --> D5[Braces_functions_and_NULL_comparisons]
D5 --> E[Check_structure_and_quality]
E --> E1[Each_commit_compiles_independently]
E1 --> E2[Code_and_docs_updated_together]
E2 --> E3[Tests_added_or_updated]
E3 --> E4[Release_notes_updated_if_needed]
E4 --> F[Assign_severity_levels]
F --> F1[Mark_missing_SPDX_Signed_off_by_or_ABI_break_as_Error]
F1 --> F2[Mark_style_violations_and_missing_Fixes_as_Warning]
F2 --> F3[Mark_minor_suggestions_as_Info]
F3 --> G[Produce_review_report]
G --> H[End_review]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
📝 WalkthroughWalkthroughA new documentation file Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- A lot of this content duplicates existing contributor/development guidelines; consider replacing repeated sections with explicit links or concise summaries to reduce future risk of the AGENTS.md drifting out of sync with the canonical documentation.
- It might help to clarify what should happen if AGENTS.md conflicts with existing guidelines (e.g., CONTRIBUTING, coding style, ABI policy), so that both humans and AI tools know which source of truth to follow when there is ambiguity.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- A lot of this content duplicates existing contributor/development guidelines; consider replacing repeated sections with explicit links or concise summaries to reduce future risk of the AGENTS.md drifting out of sync with the canonical documentation.
- It might help to clarify what should happen if AGENTS.md conflicts with existing guidelines (e.g., CONTRIBUTING, coding style, ABI policy), so that both humans and AI tools know which source of truth to follow when there is ambiguity.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In @AGENTS.md:
- Around line 358-368: Add a language identifier to the fenced code block
showing Meson build syntax so it gets proper syntax highlighting; change the
opening fence from ``` to either ```meson (preferred) or ```python (acceptable)
for the examples that define sources = files(...) and headers = files(...),
leaving the code content and closing fence unchanged.
- Around line 60-63: Update the three fenced code blocks that show commit tag
examples so they include a language identifier (use ```text) to ensure proper
formatting; specifically change the blocks containing the "Fixes:
abcdefgh1234..." example, the block starting with "# For Coverity issues:" and
the block listing tags like "Coverity issue:", "Bugzilla ID:", "Fixes:", etc.,
to open with ```text instead of plain ``` so the tag examples and tag order
render as plain text.
- Around line 42-51: Update the fenced code block containing the commit message
examples so it includes a language specifier for proper highlighting (e.g.,
change the opening "```" to "```bash" or "```text"); locate the block that
starts with "# Good examples" and ends with the closing "```" and modify only
the opening fence to include the chosen language specifier, leaving the block
contents and closing fence unchanged.
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
AGENTS.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
AGENTS.md
42-42: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
60-60: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
67-67: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
83-83: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Sourcery review
Comment on lines
+42
to
+51
| ``` | ||
| # Good examples | ||
| ixgbe: fix offload config option name | ||
| config: increase max queues per port | ||
| net/mlx5: add support for flow counters | ||
|
|
||
| # Bad examples | ||
| Fixed the offload config option. # past tense, has period | ||
| IXGBE: Fix Offload Config # uppercase | ||
| ``` |
There was a problem hiding this comment.
Add language specifiers to all fenced code blocks for proper syntax highlighting.
Fenced code blocks throughout the document are missing language identifiers. The block at this location should specify a language (e.g., bash or text for commit message examples) to enable proper rendering and syntax highlighting.
Proposed fix: Add language specifiers
-```
+```bash
# Good examples
ixgbe: fix offload config option name
config: increase max queues per port
net/mlx5: add support for flow counters
# Bad examples
Fixed the offload config option. # past tense, has period
IXGBE: Fix Offload Config # uppercase
-```
+```🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
42-42: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In @AGENTS.md around lines 42 - 51, Update the fenced code block containing the
commit message examples so it includes a language specifier for proper
highlighting (e.g., change the opening "```" to "```bash" or "```text"); locate
the block that starts with "# Good examples" and ends with the closing "```" and
modify only the opening fence to include the chosen language specifier, leaving
the block contents and closing fence unchanged.
Comment on lines
+60
to
+63
| ``` | ||
| Fixes: abcdefgh1234 ("original commit subject") | ||
| Cc: original_author@example.com | ||
| ``` |
There was a problem hiding this comment.
Add language specifiers to code blocks showing tag examples and tag order.
These sections demonstrate commit message tags and their ordering. Each fenced code block should have a language identifier (```text is appropriate for these structured examples).
Proposed fixes: Add language specifiers
For lines 60-63:
-```
+```text
Fixes: abcdefgh1234 ("original commit subject")
Cc: original_author@example.com
-```
+```For lines 67-79:
-```
+```text
# For Coverity issues:
Coverity issue: 12345
# For Bugzilla issues:
Bugzilla ID: 12345
# For stable release backport candidates:
Cc: stable@dpdk.org
# For patch dependencies:
Depends-on: series-NNNNN ("Title of the series")
-```
+```For lines 83-95:
-```
+```text
Coverity issue:
Bugzilla ID:
Fixes:
Cc:
Reported-by:
Suggested-by:
Signed-off-by:
Acked-by:
Reviewed-by:
Tested-by:
-```
+```Also applies to: 67-79, 83-95
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
60-60: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In @AGENTS.md around lines 60 - 63, Update the three fenced code blocks that
show commit tag examples so they include a language identifier (use ```text) to
ensure proper formatting; specifically change the blocks containing the "Fixes:
abcdefgh1234..." example, the block starting with "# For Coverity issues:" and
the block listing tags like "Coverity issue:", "Bugzilla ID:", "Fixes:", etc.,
to open with ```text instead of plain ``` so the tag examples and tag order
render as plain text.
Comment on lines
+358
to
+368
| ```python | ||
| # Short list | ||
| sources = files('file1.c', 'file2.c') | ||
|
|
||
| # Long list | ||
| headers = files( | ||
| 'header1.h', | ||
| 'header2.h', | ||
| 'header3.h', | ||
| ) | ||
| ``` |
There was a problem hiding this comment.
Specify language for Meson build file syntax block.
This code block demonstrates Meson build syntax. Use a language identifier (meson or python, since Meson is Python-based) for proper highlighting.
Proposed fix: Add language specifier
-```python
+```meson
# Short list
sources = files('file1.c', 'file2.c')
# Long list
headers = files(
'header1.h',
'header2.h',
'header3.h',
)
-```
+```Alternatively, if meson syntax highlighting is not available in the target environment, ```python is acceptable since Meson is Python-based.
🤖 Prompt for AI Agents
In @AGENTS.md around lines 358 - 368, Add a language identifier to the fenced
code block showing Meson build syntax so it gets proper syntax highlighting;
change the opening fence from ``` to either ```meson (preferred) or ```python
(acceptable) for the examples that define sources = files(...) and headers =
files(...), leaving the code content and closing fence unchanged.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
NOTE: This is an auto submission for "[RFC] doc: add AGENTS.md for AI-powered code review tools".
See "http://patchwork.dpdk.org/project/dpdk/list/?series=37003" for details.
Summary by Sourcery
Documentation:
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.