[PWCI] "[RFC,v2] doc: add AGENTS.md for AI-powered code review tools"#617
[PWCI] "[RFC,v2] doc: add AGENTS.md for AI-powered code review tools"#617
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) - DPDK validation scripts (check-git-log.sh, checkpatches.sh) - Linux kernel patch submission process - SPDX License Identifier specification Key sections include: - SPDX license and copyright header requirements - Commit message format with precise limits (60 char subject, 75 char body) and tag ordering rules - C coding style including explicit comparison requirements - Forbidden tokens table derived from checkpatches.sh - API tag placement rules for experimental and internal APIs - Patch validation checklists with severity levels The forbidden tokens section documents restrictions on deprecated atomics, logging functions, threading APIs, and compiler built-ins that are checked by the existing checkpatches.sh infrastructure. Severity levels (error/warning/info) align with the exit codes and messaging from check-git-log.sh and checkpatches.sh to help automated tools prioritize feedback appropriately. References: - https://doc.dpdk.org/guides/contributing/patches.html - https://doc.dpdk.org/guides/contributing/coding_style.html - devtools/check-git-log.sh - devtools/checkpatches.sh Signed-off-by: Stephen Hemminger <stephen@networkplumber.org> Signed-off-by: 0-day Robot <robot@bytheb.org>
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
📝 WalkthroughWalkthroughAdds a new AGENTS.md documentation file that comprehensively defines AI-assisted review guidelines for DPDK contributions, covering licensing, commit message conventions, API tagging, code style enforcement, patch validation, and quality standards. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @AGENTS.md:
- Around line 24-30: Change every Markdown code fence that contains C examples
to include the language identifier "c" on the opening backticks; e.g., replace
opening fences like ``` that wrap blocks beginning with "/*
SPDX-License-Identifier: BSD-3-Clause" or containing lines such as "#include
<stdio.h>" with ```c so all C snippets throughout the document (including the
other C blocks noted in the review) explicitly specify the C language.
- Around line 57-69: The fenced code blocks in the examples lack language
specifiers and should be updated to include appropriate languages for syntax
highlighting; locate the commit-message example block (the Good/Bad examples
showing net/ixgbe etc.) and the Fixes/tag example blocks referenced (around the
tag examples at 121–123, 135–147, and 153–165) and change the opening fences
from ``` to a language-specific fence such as ```text or ```diff where
appropriate (leave the closing ``` as-is), ensuring each example block has a
proper language label for readability.
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
AGENTS.md
🧰 Additional context used
🪛 LanguageTool
AGENTS.md
[style] ~601-~601: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...y in headers - [ ] Alignment attributes only on struct/union - [ ] Packed attributes...
(ADVERB_REPETITION_PREMIUM)
🪛 markdownlint-cli2 (0.18.1)
AGENTS.md
57-57: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
121-121: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
135-135: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
153-153: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
685-685: Bare URL used
(MD034, no-bare-urls)
🔇 Additional comments (2)
AGENTS.md (2)
1-693: Comprehensive and well-structured reference document for AI-assisted code review.The document effectively consolidates DPDK contribution guidelines into a machine-readable format. The organization into sections (licensing, commit messages, coding style, forbidden tokens, API tags, validation, severity levels) is logical and supports AI tool automation. The use of tables, checklists, and explicit examples makes the guidance actionable and testable.
Strengths:
- Clear severity levels (Error/Warning/Info) that align with automation priorities
- Comprehensive forbidden token tables with preferred alternatives
- Specific commit message rules with examples of common mistakes
- Validation checklist provides a template for AI tool behavior
- API tag placement rules are precise and unambiguous
Minor observations:
- The document is quite long (693 lines); consider if it needs an index or quick-reference section for frequently-checked rules
- Some rules rely on external files (e.g.,
devtools/words-case.txt) that are not included; ensure these remain current and accessible
623-633: Specify language for Meson build example.The Meson build file example at lines 623–633 should specify
pythonas the language (Meson uses Python-like syntax).🔧 Proposed fix
-``` +```python # Short list sources = files('file1.c', 'file2.c') ... -``` +```Likely an incorrect or invalid review comment.
| ```c | ||
| /* SPDX-License-Identifier: BSD-3-Clause | ||
| * Copyright(c) 2024 ExampleCorp | ||
| */ | ||
|
|
||
| #include <stdio.h> | ||
| ``` |
There was a problem hiding this comment.
Specify language for all C code examples.
All C code examples throughout the document (in licensing, style, API tag, and other sections) should specify c as the language identifier. Examples include lines 24–30, 209–219, 223–230, 277–308, 312–319, 323–333, 347–352, 362–369, 469–479, 487–491, 499–505, and 515–523.
🔧 Example fix pattern
-```
+```c
/* SPDX-License-Identifier: BSD-3-Clause
* Copyright(c) 2024 ExampleCorp
*/
#include <stdio.h>
-```
+```Also applies to: 209-219, 223-230, 277-308, 312-319, 323-333, 347-352, 362-369, 469-479, 487-491, 499-505, 515-523
🤖 Prompt for AI Agents
In @AGENTS.md around lines 24 - 30, Change every Markdown code fence that
contains C examples to include the language identifier "c" on the opening
backticks; e.g., replace opening fences like ``` that wrap blocks beginning with
"/* SPDX-License-Identifier: BSD-3-Clause" or containing lines such as "#include
<stdio.h>" with ```c so all C snippets throughout the document (including the
other C blocks noted in the review) explicitly specify the C language.
| ``` | ||
| # Good examples | ||
| net/ixgbe: fix offload config option name | ||
| config: increase max queues per port | ||
| net/mlx5: add support for flow counters | ||
| app/testpmd: fix memory leak in flow create | ||
|
|
||
| # Bad examples | ||
| Fixed the offload config option. # past tense, has period, no prefix | ||
| net/ixgbe: Fix Offload Config # uppercase after colon | ||
| ixgbe: fix something # wrong prefix, should be net/ixgbe | ||
| lib/ethdev: add new feature # wrong prefix, should be ethdev: | ||
| ``` |
There was a problem hiding this comment.
Add language specifiers to fenced code blocks.
Multiple code blocks throughout the document lack language specifiers, which impacts readability and syntax highlighting. For example, the example commit messages at lines 57–69 and tag examples at lines 121–123, 135–147, and 153–165 should specify appropriate languages (e.g., text, diff, etc.).
🔧 Examples of fixes needed
-# Good examples
+```text
+# Good examples
net/ixgbe: fix offload config option name
config: increase max queues per port
...
-```
+```
+
+# And for the Fixes tag example:
-```
+```text
Fixes: abcdefgh1234 ("original commit subject")</details>
Also applies to: 121-123, 135-147, 153-165
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.18.1)</summary>
57-57: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In @AGENTS.md around lines 57 - 69, The fenced code blocks in the examples lack
language specifiers and should be updated to include appropriate languages for
syntax highlighting; locate the commit-message example block (the Good/Bad
examples showing net/ixgbe etc.) and the Fixes/tag example blocks referenced
(around the tag examples at 121–123, 135–147, and 153–165) and change the
opening fences from to a language-specific fence such astext or diff where appropriate (leave the closing as-is), ensuring each example block has
a proper language label for readability.
</details>
<!-- fingerprinting:phantom:triton:mongoose -->
<!-- This is an auto-generated comment by CodeRabbit -->
2 participants
NOTE: This is an auto submission for "[RFC,v2] doc: add AGENTS.md for AI-powered code review tools".
See "http://patchwork.dpdk.org/project/dpdk/list/?series=37008" for details.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.