kleaf: add creating-kernel-commits skill and evals Introduce the creating-kernel-commits skill to guide AI coding assistants when drafting commit messages in Android kernel and tooling repositories. The skill outlines general format rules (summary, body, trailers sections), project-specific guidelines (ACK, Kleaf, build-tools, external), and AI-specific rules (no sign-offs, mandatory Assisted-by). Also include the EVAL.yaml file with evaluation test cases to verify the skill. TAG=agy CONV=15751285-e0e5-4948-8b57-6a792ed63561 Bug: 507499871 Test: From <workspace_root>/build/kernel: run_evals.py --skill_dir .agents/skills/creating_kernel_commits Assisted-by: Antigravity:Gemini-Next Change-Id: I931800842f8c1568dd83940137102bcb17cde28d
diff --git a/.agents/skills/creating_kernel_commits/EVAL.yaml b/.agents/skills/creating_kernel_commits/EVAL.yaml new file mode 100644 index 0000000..8489f27 --- /dev/null +++ b/.agents/skills/creating_kernel_commits/EVAL.yaml
@@ -0,0 +1,217 @@ +suite_name: creating-kernel-commits +timeout_seconds: 300 +max_tool_calls: 50 + +cases: + - name: ack_cherry_pick_upstream + prompt: > + I want to cherry-pick an upstream commit to the ACK `common` repository. + The original commit message is: + + sched/fair: fix bug in enqueue + + This fixes a null pointer dereference in enqueue_task_fair. + + Signed-off-by: John Doe <john.doe@example.com> + + The Android bug is 123456789. The cherry-picked SHA is `abcdef1234567890abcdef1234567890abcdef12`. + Please draft the commit message for me. Print the drafted commit message in your response. + skills: [creating-kernel-commits] + rubric: | + The agent must: + - Prefix the subject with 'UPSTREAM:'. + - Preserve the original subject and body. + - Add 'Bug: 123456789' footer. + - Add '(cherry picked from commit ...)' footer. + - Do NOT add 'Assisted-by:' footer (since this is a clean cherry-pick). + - If TAG= and CONV= tags are present, place them in a section BEFORE the standard footers (Bug/Test). + - NOT add a Signed-off-by tag for the agent or user. + - Prompt the user to sign off themselves. + expect_keywords: + - "UPSTREAM: sched/fair: fix bug in enqueue" + - "Signed-off-by: John Doe <john.doe@example.com>\n\n" + - "Bug: 123456789" + - "(cherry picked from commit abcdef1234567890abcdef1234567890abcdef12)" + - "amend" + - "sign" + forbid_keywords: + - "Assisted-by:" + + - name: kleaf_ad_hoc_change + prompt: > + I made a change in `build/kernel` to support a new bazel flag `--experimental_foo`. + I want to commit it. The change was validated by running `tools/bazel test //build/kernel/kleaf/tests/examples:examples_test`. + Please draft the commit message. + skills: [creating-kernel-commits] + rubric: | + The agent must: + - Prefix the subject with 'kleaf:'. + - Keep the subject line short (ideally under 50 characters). + - Include a mandatory 'Test:' footer with the bazel command used. + - Include 'Assisted-by:' footer. + - NOT add Signed-off-by. + expect_keywords: + - "kleaf:" + - "Test:" + - "tools/bazel test //build/kernel/kleaf/tests/examples:examples_test" + - "Assisted-by:" + + - name: prebuilts_toolchain_ad_hoc + prompt: > + I updated the `update-prebuilts.sh` script in `prebuilts/kernel-build-tools` to fix a path issue. + I verified it by running the script manually. + Please draft the commit message. Draft the message based on this description, without checking the repository. Print the drafted commit message in your response. + skills: [creating-kernel-commits] + rubric: | + The agent must: + - NOT use the 'kleaf:' prefix in the subject (as it is prebuilts/kernel-build-tools). + - Include a mandatory 'Test:' footer describing how it was verified. + - Include 'Assisted-by:' footer. + - If TAG= and CONV= tags are present, place them in a section BEFORE the standard footers (Bug/Test/Assisted-by). + - NOT add Signed-off-by. + expect_keywords: + - "Test:" + - "Assisted-by:" + + - name: ack_revert_non_standard_footer + prompt: > + I need to revert a commit in `common` repository. + The commit being reverted is `a1b2c3d4e5f6` ("ANDROID: sched: fix something"). + The reason for revert is that it breaks power measurements on Cuttlefish. + The Android bug is 987654321. + Please draft the commit message. Print the drafted commit message in your response. + skills: [creating-kernel-commits] + rubric: | + The agent must: + - Subject starts with 'Revert "ANDROID: sched: fix something"'. + - Body contains 'This reverts commit a1b2c3d4e5f6...'. + - 'Reason for revert:' must be in its own section (surrounded by blank lines) because it has spaces. + - If TAG= and CONV= tags are present, place them in a section BEFORE the standard footers (Bug/Test/Assisted-by). + - Include 'Assisted-by:' footer. + - Prompt the user to sign off. + expect_keywords: + - "Revert \"ANDROID: sched: fix something\"" + - "This reverts commit a1b2c3d4e5f6" + - "Reason for revert:" + - "Bug: 987654321" + - "Assisted-by:" + + - name: ack_cherry_pick_fromgit + prompt: > + I want to cherry-pick a commit that is in a maintainer tree but not yet in mainline. + Original commit message: + + scsi: ufs: fix potential deadlock + + This fixes a deadlock scenario in the error handler. + + Signed-off-by: Alice Smith <alice@example.com> + + The Android bug is 111222333. + The source commit SHA is `1234567890abcdef1234567890abcdef12345678`. + The repo is `https://git.kernel.org/pub/scm/linux/kernel/git/mkp/scsi.git`. + The branch is `for-next`. + Please draft the commit message. Print the drafted commit message in your response. + skills: [creating-kernel-commits] + rubric: | + The agent must: + - Prefix the subject with 'FROMGIT:'. + - Preserve the original subject, body, and Sign-off. + - Add 'Bug: 111222333' footer. + - Add '(cherry picked from commit ...)' line with SHA, repo URL, and branch. + - If TAG= and CONV= tags are present, place them in a section BEFORE the standard footers (Bug/Test). + - Do NOT add 'Assisted-by:' footer (since this is a clean cherry-pick). + - NOT add Signed-off-by. + - Prompt the user to sign off. + expect_keywords: + - "FROMGIT: scsi: ufs: fix potential deadlock" + - "Signed-off-by: Alice Smith <alice@example.com>\n\n" + - "cherry picked from commit 1234567890abcdef1234567890abcdef12345678\n https://git.kernel.org/pub/scm/linux/kernel/git/mkp/scsi.git for-next" + - "amend" + - "sign" + forbid_keywords: + - "Assisted-by:" + + - name: ack_cherry_pick_fromlist + prompt: > + I want to cherry-pick a patch that was submitted to LKML but is not in any tree yet. + Original commit message: + + net: core: optimize packet handling + + This improves throughput by 5%. + + Signed-off-by: Bob Brown <bob@example.com> + + The Android bug is 444555666. + The mailing list link is `https://lore.kernel.org/lkml/20260520123456.GA12345@example.com/`. + Please draft the commit message. Print the drafted commit message in your response. + skills: [creating-kernel-commits] + rubric: | + The agent must: + - Prefix the subject with 'FROMLIST:'. + - Preserve the original subject, body, and Sign-off. + - Add 'Bug: 444555666' footer. + - Add 'Link:' footer with the lore.kernel.org link. + - If TAG= and CONV= tags are present, place them in a section BEFORE the standard footers (Bug/Test). + - Do NOT add 'Assisted-by:' footer (since this is a clean cherry-pick). + - NOT add Signed-off-by. + - Prompt the user to sign off. + expect_keywords: + - "FROMLIST: net: core: optimize packet handling" + - "Signed-off-by: Bob Brown <bob@example.com>\n\n" + - "Link: https://lore.kernel.org/lkml/20260520123456.GA12345@example.com/" + - "amend" + - "sign" + forbid_keywords: + - "Assisted-by:" + + - name: ack_missing_bug_number + prompt: > + I want to cherry-pick an upstream commit to the ACK `common` repository. + The original commit message is: + + sched/fair: fix bug in enqueue + + This fixes a null pointer dereference in enqueue_task_fair. + + Signed-off-by: John Doe <john.doe@example.com> + + The cherry-picked SHA is `abcdef1234567890abcdef1234567890abcdef12`. + Please draft the commit message for me. + skills: [creating-kernel-commits] + rubric: | + The agent must: + - Ask the user to provide a bug ID/number. + expect_keywords_any: + - "bug" + - "ask" + - "provide" + - "request" + + # Needed due to b/517689798 + - name: kleaf_ad_hoc_change_with_tags + prompt: > + I made a change in `build/kernel` to support a new bazel flag `--experimental_foo`. + I want to commit it. + No tests were run, and no Test: line is needed. + No bug was filed, and no Bug: line is needed. + Please draft the commit message. + Include the following tracking tags: `TAG=agy` and `CONV=12345`. + skills: [creating-kernel-commits] + rubric: | + The agent must: + - Prefix the subject with 'kleaf:'. + - Keep the subject line short (ideally under 50 characters). + - Include 'Assisted-by:' footer. + - Place TAG= and CONV= tags in a section BEFORE the standard footer (Assisted-by). + - NOT add Signed-off-by. + - NOT include a 'Test:' footer. + - NOT include a 'Bug:' footer. + expect_keywords: + - "kleaf:" + - "Assisted-by:" + expect_keywords_any: + - "TAG=agy\nCONV=12345\n\nAssisted-by:" + - "TAG=agy\nCONV=12345\n\nTest:" + - "TAG=agy\nCONV=12345\n\nBug:"
diff --git a/.agents/skills/creating_kernel_commits/SKILL.md b/.agents/skills/creating_kernel_commits/SKILL.md new file mode 100644 index 0000000..9efb350 --- /dev/null +++ b/.agents/skills/creating_kernel_commits/SKILL.md
@@ -0,0 +1,140 @@ +--- +name: creating-kernel-commits +description: Android kernel commit process and commit message format. Activate this when ready to commit code in kernel, GKI, Android kernel tooling, etc. repositories, but not for platform repositories. +--- + +# Commit process + +1. Make sure tests have passed before starting the commit process. +2. Create a changelist with a comprehensive commit message (mentioning + build/test status and any persistent lint issues) in every git repository + you have made edits within. + +# Commit messages - follow a strict format + +You MUST follow these strict format rules when drafting the commit message: + +1. A 50-character summary line. Maintain this 50-character limit as much as possible, unless the subject really must exceed it. + * **Exception:** When cherry-picking a change from upstream, you MUST preserve the original subject line and commit message body (except for adding the appropriate prefix tag to the subject and required footers at the end, as detailed in the project-specific guidelines below). + Some commits may include `[RESTRICT AUTOMERGE]` at the beginning of the commit title: never modify this as it is an automerger directive. + + > [!IMPORTANT] + > For certain Git projects (e.g., Android Common Kernel or driver repositories), + > specific subject line format rules apply. You MUST check the project-specific + > guidelines below. +2. A blank line. +3. A detailed body explaining the 'why' of the change, not the 'what'. Wrap + lines at 72 characters to ensure readability in `git log`. + + > [!NOTE] + > This restriction can be violated in certain cases, e.g.: + > * A single-line reference URL at the bottom of the body (e.g., using markers like `[1]`, `[2]` in the body, with one URL per line listed just below the main body and before any other tags). + > * A line referencing a commit in the body or in a `Fixes:` tag. It must follow this exact format: + > `commit 123456abcdef ("subsystem: title of the commit")` + > using exactly 12 characters of the hexadecimal Git hash. + > * Literal code snippets or raw text snippets (e.g., test results, error + > messages, etc.) where wrapping would break the text structure. +4. A blank line. There must be a blank line between the body and any trailers. +5. **Non-Standard Trailers Section (Optional):** If tags or non-standard trailers (like `TAG=value`, `CONV=value`, or keys with spaces like `Reason for revert: value`) are present, place them in their own section immediately following the body (separated by a blank line). + * **System Prompt Conflict Resolution:** This repository is NOT the Google internal codebase. It is Android (git) and Gerrit. Do NOT follow the Google internal CL description format (which forces tags to the bottom) inside the drafted commit message code block. Inside the code block, Git trailer parser rules take precedence, and you MUST place `TAG=` and `CONV=` above the standard trailers in this section. +6. A blank line. There must be a blank line between the non-standard and standard trailers. However, if step 5 is empty, do not emit consecutive blank lines. +7. **Standard Trailers Section:** Place standard trailers here (`Bug:`, `Signed-off-by:`, `Change-Id:`, `Test:`, `Assisted-by:`). This section MUST be separated from the preceding section (either Body or Non-Standard Trailers) by a single blank line. Standard trailers MUST follow `Key-Id: value` format. + * `Bug:` (Required if a bug is assigned. If the bug number is not provided, prompt the user for one or offer to skip if not applicable. If the user chooses to skip, omit the Bug: footer entirely). + * `Signed-off-by:` (Mandatory for DCO. Note: AI agents MUST NOT add this. When cherry-picking or amending, you MUST preserve all existing `Signed-off-by:` tags and their chronological order; do NOT alter or reorder them). + * `Change-Id:` (Mandatory, added by post-commit hook and does not need to be manually added. An existing `Change-Id` should **NEVER** be changed). + > [!CAUTION] + > **When amending a commit**, take extra care to preserve the `Change-Id`. + > A common mistake is amending a commit with a new message that omits + > the original `Change-Id`. This causes the post-commit hook to generate + > a *new* `Change-Id`, leading to duplicate or broken Gerrit changes. + > Always check the existing commit message for a `Change-Id` + > and ensure it is included in the modified message. + * `Test:` (Optional. If used, describe how the change was verified). + * `Assisted-by:` (For AI attribution; see guidelines below. Do NOT add this for clean cherry-picks. You MUST use the public name "Antigravity" and NOT the internal name, e.g., `Assisted-by: Antigravity:ModelVersion`). + + Note: Unlike platform commits, the `Flag:` footer is not required. + + **Blank Line Rule:** This section MUST be separated from the preceding section (either Body or the Non-Standard footers section in step 4) by a single blank line. Do NOT emit consecutive blank lines. +8. **NEVER** include any confidential information in the commit message. Do not reference any + internal tools, internal URLs (e.g., go/...), project names, device codenames, partner + references, unannounced features, internal mailing lists, or internal employee names. Write the + message under the strict assumption that it will be immediately public via the Android Open + Source Project (AOSP). +9. **AI Sign-off:** AI agents MUST NOT add `Signed-off-by:` tags. You MUST prompt the user to sign off themselves (e.g., reminding them to run `git commit --amend --signoff`) outside the code block. + + +# Project-specific Subject Line Guidelines + +## ACK and Driver Repositories + +When creating commit messages for certain Git projects (like the Android Common Kernel or driver repositories), the agent MUST read and strictly follow the detailed instructions in the files listed below. + +First, locate the Android Common Kernel repository (project `kernel/common`). In some manifests, it may not be checked out at `common/`. Find the correct path by running the following command from the workspace root: +```bash +repo list -p kernel/common +``` +Use the path returned by this command (referred to as `<common_path>` below) to locate these files: + +* `<common_path>/README.md` - For patch requirements, subject tags (`UPSTREAM:`, `BACKPORT:`, `FROMGIT:`, `FROMLIST:`, `ANDROID:`), and signature tags. +* `<common_path>/Documentation/process/submitting-patches.rst` - For standard subject format (`subsystem: summary phrase`) and wrapping rules. +* `<common_path>/Documentation/process/coding-assistants.rst` - For AI usage guidelines (specifically: attribution and sign-off rules). + +> [!NOTE] +> For `FROMGIT` commits, the cherry-pick footer must format the URL and branch on a second line, prefixed with a single space: +> `(cherry picked from commit <sha1>` +> ` <repo_url> <branch>)` + +> [!IMPORTANT] +> The short summary below is only a quick reference. You MUST read all three files listed above in their entirety before writing a commit message. + +### Short Summary: +1. **Subject Format:** Use `TAG: subsystem: summary phrase` (e.g., `ANDROID: sched/fair: fix...`). Note that the subject tag (like `ANDROID:`, `UPSTREAM:`, etc.) only applies to the common kernel / GKI Git repository, and usually does not apply to external driver Git repositories (which just use `subsystem: summary phrase`). + * You MUST read `<common_path>/README.md` to apply the appropriate subject tags (`UPSTREAM:`, `BACKPORT:`, `FROMGIT:`, `FROMLIST:`, `ANDROID:`). +2. **Subject Length:** Maintain 50 characters as much as possible; must not exceed 70-75 characters (unless preserving an upstream cherry-pick subject). +3. **AI Sign-off:** AI agents MUST NOT add `Signed-off-by:` tags. You MUST prompt the user to sign off themselves after reviewing the change (e.g., by suggesting they run `git commit --amend --signoff`). +4. **AI Attribution:** Add `Assisted-by: <AgentName>:<ModelVersion>` to the commit message. Note that for cherry-picks (clean upstream patches, e.g. `UPSTREAM:`, `FROMGIT:`, `FROMLIST:`), you MUST NOT add the `Assisted-by:` footer unless the cherry-pick required conflict resolution or backporting (which involved the AI modifying or generating code). For standard development commits (e.g. `ANDROID:`, `kleaf:`), always add the `Assisted-by:` footer. + * e.g. If you are using the Gemini-Next model, you MUST use `Assisted-by: Antigravity:Gemini-Next`. You MUST use the public name "Antigravity" and NOT the internal name. +5. **New Footers Section:** For all cherry-picks (using tags like `ANDROID:`, `FROMGIT:`, `FROMLIST:`, `UPSTREAM:`, `BACKPORT:`), all new footers (e.g., `Bug:`, `Test:`, `Change-Id:`, `Assisted-by:` [if required], `(cherry picked from...)`) MUST be placed in their own section at the end of the message, separated from the original commit's trailers (like the original `Signed-off-by:`) by a blank line. + +## Kleaf Repositories (build/kernel) + +These guidelines apply to the following repositories: +* `build/kernel` +* `prebuilts/clang` (specifically when editing the `kleaf` subdirectory in it). + +### Guidelines: +1. **Default Prefix:** When making changes in `build/kernel` or `prebuilts/clang` (within the `kleaf` subdirectory), the commit subject line **usually** starts with `kleaf: ` (e.g., `kleaf: support new bazel flag`). You can optionally add a subcomponent prefix if applicable (e.g., `kleaf: tests: ...` or `kleaf: docs: ...`). + * **General Exception:** If the change has nothing to do with Bazel or Kleaf (rare, e.g., updating scripts in `build/kernel/abi/` or `build/kernel/static_analysis/`), omit the `kleaf: ` prefix and use a relevant subsystem/area prefix (e.g., `abi: ...` or `static_analysis: ...`). +2. **AI Guidelines:** The same AI usage guidelines (no `Signed-off-by:` tags, and mandatory `Assisted-by:` tag) from `<common_path>/Documentation/process/coding-assistants.rst` apply to these repositories as well (there is no need to remind the user to sign off). Refer to the ACK section above for instructions on how to locate the `<common_path>`. +3. **Test Footer:** The `Test:` line is **mandatory** (MUST be present). It should describe how the change was validated, usually by attaching the relevant Bazel command or test name (e.g., `Test: tools/bazel test //build/kernel/...` or `Test: kleaf_integration_test`). +4. **Bazel Formatting:** If you have modified Bazel files (`BUILD`, `WORKSPACE`, `.bazel`, `.bzl`), check if `buildifier` is available in the environment. If so, format the files. If not, or to be safe, remind the user to format the Bazel files or confirm that they are formatted correctly. + +## Prebuilts Kernel Build Tools (prebuilts/kernel-build-tools) + +Changes to `prebuilts/kernel-build-tools` are handled based on how they are performed: + +### Automated Updates: +Most changes in `prebuilts/kernel-build-tools` are performed by automated scripts or by the following skills. In these cases, the commit message should be left **as-is** (generated by the script/skill): +* `updating-bazel-binary` +* `updating-kernel-build-tools` + +### Ad Hoc Modifications: +If you are making ad hoc modifications (e.g., updating helper scripts like `update-prebuilts.sh` or Bazel build rules like `BUILD.bazel`), follow these guidelines: +1. **General Guidelines:** The general commit message guidelines (Steps 1-7) MUST be followed. +2. **AI Guidelines:** The AI usage guidelines (no `Signed-off-by:` tags, and mandatory `Assisted-by:` tag) apply (there is no need to remind the user to sign off). Refer to the ACK section above for instructions on how to locate the `<common_path>`. +3. **Test Footer:** The `Test:` line is **mandatory** (MUST be present), describing how the change was validated (e.g., attaching Bazel commands or test names). + +## External Repositories (external/*) + +Changes to `external/*` repositories (related to kernel/Kleaf builds) are handled based on how they are performed: + +### Automated Updates: +Most changes in `external/*` are performed by automated scripts or by the following skills. In these cases, the commit message should be left **as-is** (generated by the script/skill): +* `updating-external-bazel-projects` +* `updating-bazel-central-registry` + +### Ad Hoc Modifications: +If you are making ad hoc modifications that are NOT upstreamed, follow these guidelines: +1. **General Guidelines:** The general commit message guidelines (Steps 1-7) MUST be followed. +2. **AI Guidelines:** The AI usage guidelines (no `Signed-off-by:` tags, and mandatory `Assisted-by:` tag) apply (there is no need to remind the user to sign off). Refer to the ACK section above for instructions on how to locate the `<common_path>`. +3. **Test Footer:** The `Test:` line is **mandatory** (MUST be present), describing how the change was validated (e.g., attaching Bazel commands or test names).