[PATCH BlueZ v1 1/3] doc: Add commit message guidelines for AI coding assistants

[PATCH BlueZ v1 1/3] doc: Add commit message guidelines for AI coding assistants

[Luiz Augusto von Dentz]

From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>

Require commit messages to record only the changes and their rationale,
to follow Rule 2 of the maintainer guidelines, and to have their factual
claims checked against the diff.

Inspired by WirePlumber's AGENTS.md:
https://gitlab.freedesktop.org/pipewire/wireplumber/-/blob/master/AGENTS.md

Assisted-by: OpenCode:claude-opus-5.5
---
 doc/coding-assistants.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/doc/coding-assistants.rst b/doc/coding-assistants.rst
index 3a643527fd65..778b3e6d81b3 100644
--- a/doc/coding-assistants.rst
+++ b/doc/coding-assistants.rst
@@ -45,3 +45,25 @@ Basic development tools (git, gcc, make, editors) should not be listed.
 Example::
 
   Assisted-by: Claude:claude-3-opus coccinelle sparse
+
+Commit Messages
+===============
+
+Commit messages must follow Rule 2 in doc/maintainer-guidelines.rst.
+
+A commit message records only the changes being made and the rationale
+for them. For each sentence in a draft, ask what change it records or
+what decision it justifies. If the answer is neither, delete it. In
+particular, cut anything that:
+
+* explains something the project's developers already know
+* restates general knowledge about the language, toolkits, or codebase
+* restates what the diff already shows (e.g. listing touched functions)
+* narrates the reasoning behind an earlier, abandoned attempt
+
+Additionally:
+
+* Keep it brief; use bullets only when listing multiple distinct changes.
+* Use a subject prefix consistent with the history of the files touched.
+* Verify factual claims in the message (file counts, symbol names,
+  paths) against the actual diff before committing.
-- 
2.55.0

[PATCH BlueZ v1 2/3] doc: Add bug fixing procedure for AI coding assistants

[Luiz Augusto von Dentz]

From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>

Require AI assistants fixing bugs to verify them with a reproducer, test
the fix, state what could not be verified and leave any submission to
the human, with vulnerabilities following SECURITY.md.

Adapted from the Linux kernel's
Documentation/process/coding-assistants.rst.

Assisted-by: OpenCode:claude-opus-5.5
---
 doc/coding-assistants.rst | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/doc/coding-assistants.rst b/doc/coding-assistants.rst
index 778b3e6d81b3..6b81d740cd65 100644
--- a/doc/coding-assistants.rst
+++ b/doc/coding-assistants.rst
@@ -67,3 +67,36 @@ Additionally:
 * Use a subject prefix consistent with the history of the files touched.
 * Verify factual claims in the message (file counts, symbol names,
   paths) against the actual diff before committing.
+
+Procedure for finding and fixing bugs
+=====================================
+
+When an AI assistant is used to find and fix bugs, it **MUST** follow at
+least these steps:
+
+1. Before starting, read the whole process documentation listed above,
+   as well as any other document mentioned in the request. Do not rely on
+   isolated parts found by keyword search.
+2. Note the commit ID and locate the bug as instructed.
+3. For any bug that is not trivial, verify that it is real by writing a
+   reproducer, preferably a unit test (unit/) or a functional test
+   (test/functional/, see doc/functional-testing.rst). Unverified reports
+   are often invalid and may be ignored. Stop here if the bug turns out
+   not to be real.
+4. Write a fix for the bug. Fixes written in the same session that found
+   the bug tend to be more accurate, as the reasoning context is still
+   present.
+5. Build and verify that the fix works, using the reproducer or by
+   re-running the analysis; drop any fix that doesn't work and try
+   another one. The fix must not add build warnings, must pass
+   ``make check`` and the checkpatch.pl checks (see doc/coding-style.rst).
+6. Commit the fix with a message describing the problem and the solution,
+   following the Commit Messages section above. Add a Fixes tag pointing
+   to the commit that introduced the bug and an Assisted-by tag as
+   described above.
+7. Indicate what could not be done. If the fix could not be built or
+   tested, or no reproducer could be produced, say so explicitly.
+8. Determine whether the bug is a vulnerability. Vulnerabilities must not
+   be reported to the mailing list; follow SECURITY.md instead. Regular
+   bugs are sent to linux-bluetooth@vger.kernel.org. Leave the submission
+   to the human; the assistant must never send anything itself.
-- 
2.55.0

[PATCH BlueZ v1 3/3] Add AGENTS.md symlink to doc/coding-assistants.rst

[Luiz Augusto von Dentz]

From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>

Let AI coding assistants that look for AGENTS.md load the guidelines
automatically.

Assisted-by: OpenCode:claude-opus-5.5
---
 AGENTS.md | 1 +
 1 file changed, 1 insertion(+)
 create mode 120000 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 120000
index 000000000000..f219acfe818d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1 @@
+doc/coding-assistants.rst
\ No newline at end of file
-- 
2.55.0

RE: [BlueZ,v1,1/3] doc: Add commit message guidelines for AI coding assistants

[bluez.test.bot]

[-- Attachment #1: Type: text/plain, Size: 1990 bytes --]

This is automated email and please do not reply to this email!

Dear submitter,

Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/series/1177764/

---Test result---

Test Summary:
CheckPatch                    FAIL      1.04 seconds
GitLint                       PASS      0.83 seconds
BuildEll                      PASS      13.41 seconds
BluezMake                     PASS      234.91 seconds
MakeCheck                     PASS      13.12 seconds
MakeDistcheck                 PASS      104.58 seconds
CheckValgrind                 PASS      160.10 seconds
CheckSmatch                   PASS      167.39 seconds
bluezmakeextell               PASS      62.04 seconds
TestFunctional                PASS      808.73 seconds
IncrementalBuild              PASS      234.15 seconds
ScanBuild                     PASS      661.38 seconds

Details
##############################
Test: CheckPatch - FAIL
Desc: Run checkpatch.pl script
Output:
[BlueZ,v1,1/3] doc: Add commit message guidelines for AI coding assistants
WARNING:BAD_SIGN_OFF: Do not use whitespace before Assisted-by:
#117: FILE: doc/coding-assistants.rst:47:
   Assisted-by: Claude:claude-3-opus coccinelle sparse

/home/runner/work/bluez/bluez/src/patch/14861431.patch total: 0 errors, 1 warnings, 25 lines checked

NOTE: For some of the reported defects, checkpatch may be able to
      mechanically convert to the typical style using --fix or --fix-inplace.

/home/runner/work/bluez/bluez/src/patch/14861431.patch has style problems, please review.

NOTE: Ignored message types: COMMIT_MESSAGE COMPLEX_MACRO CONST_STRUCT FILE_PATH_CHANGES MISSING_SIGN_OFF PREFER_PACKED SPDX_LICENSE_TAG SPLIT_STRING SSCANF_TO_KSTRTO

NOTE: If any of the errors are false positives, please report
      them to the maintainer, see CHECKPATCH in MAINTAINERS.




https://github.com/bluez/bluez/pull/2619

---
Regards,
Linux Bluetooth

Re: [PATCH BlueZ v1 1/3] doc: Add commit message guidelines for AI coding assistants

[patchwork-bot+bluetooth]

Hello:

This series was applied to bluetooth/bluez.git (master)
by Luiz Augusto von Dentz <luiz.von.dentz@intel.com>:

On Thu,  1 Oct 2026 11:10:52 -0400 you wrote:
> From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
> 
> Require commit messages to record only the changes and their rationale,
> to follow Rule 2 of the maintainer guidelines, and to have their factual
> claims checked against the diff.
> 
> Inspired by WirePlumber's AGENTS.md:
> https://gitlab.freedesktop.org/pipewire/wireplumber/-/blob/master/AGENTS.md
> 
> [...]

Here is the summary with links:
  - [BlueZ,v1,1/3] doc: Add commit message guidelines for AI coding assistants
    https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=798da8d7ace2
  - [BlueZ,v1,2/3] doc: Add bug fixing procedure for AI coding assistants
    https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=17ea5080c481
  - [BlueZ,v1,3/3] Add AGENTS.md symlink to doc/coding-assistants.rst
    https://git.kernel.org/pub/scm/bluetooth/bluez.git/?id=2f1ae1462507

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html