manage-commits

name	manage_commits
description	A skill for creating, amending, formatting, and uploading commits in the AndroidX frameworks/support project

Manage Commits Skill (AndroidX)

Enforces AndroidX conventions for formatting, updating APIs, drafting commit messages, and uploading changes in frameworks/support. Follow steps in order.

Steps

• Step 0: Workspace Preparation & Branching
• Step 1: Analyze Changes (Initial Status)
• Step 2: Format Code and Update APIs
• Step 3: Review Final Diff
• Step 4: Draft Commit Message & Handle Tags
• Step 5: Commit, Best Practices & Upload

---

0. Workspace Preparation & Branching

AndroidX development in the frameworks/support directory uses Git and the Repo tool.

• Ensure you are in the correct workspace directory (frameworks/support/).
• Ensure you are on a working branch.
  • Start branch: repo start <branch_name> ..
  • You can start a branch even with existing uncommitted changes.

1. Analyze Changes (Initial Status)

Identify modified or added files to know what needs formatting and API updates.

• Identify changed and untracked files:

  git status
  

• Note modified .kt, .ktx, .java files, and potential public API changes.

2. Format Code and Update APIs

Format modified files and update public APIs using the list from Step 1.

• Kotlin Formatting:

  • Run ktfmt on modified .kt/.ktx files to auto-correct style violations:

    ./gradlew :ktCheckFile --format --file <file_path>
    

    Repeat --file <file_path> for multiple files.

• Java Formatting:

  • If you modified Java files, run javaFormat on the affected module (e.g., :appcompat:appcompat-resources):

    ./gradlew :appcompat:appcompat-resources:javaFormat
    

• Markdown Files:

  • There is no automatic formatter for Markdown (.md) files.
  • You must remove trailing whitespaces (spaces or tabs at the end of lines) in modified .md files before committing.
  • Run the following command to remove trailing whitespaces:
    • On macOS:

      sed -i '' 's/[[:space:]]*$//' <file_path>
      

    • On Linux:

      sed -i 's/[[:space:]]*$//' <file_path>
      

• Public API Tracking:

  • If public APIs changed, you must update the corresponding current.txt files in the api/ directory by running updateApi on the affected module (e.g., :appcompat:appcompat-resources):

    ./gradlew :appcompat:appcompat-resources:updateApi
    

    Or globally (takes longer): ./gradlew updateApi

3. Review Final Diff

Review the final clean state of the changes (including formatting and API updates) before drafting the commit message.

• Review the full diff of all uncommitted changes:

  git diff
  

  Or for staged changes: git diff --staged
• Verify only intended changes are included.

4. Draft Commit Message & Handle Tags

Write a clear commit message adhering to conventions based on the final diff, and group all tags in a contiguous block at the very end.

• Subject: Concise imperative summary (e.g., "Fix Popup positioning offset bugs"), <100 characters.

• Body: Explain why changes were made (rationale/background), not just what changed. Separate from subject with a blank line.

• Test: tag (REQUIRED):

  • Every commit MUST have a Test: stanza detailing how it was verified. This should describe the test that validates the behavior changed.
  • Provide exact test command: Test: ./gradlew :compose:ui:ui:connectedAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=androidx.compose.ui.window.PopupTest
  • If tests aren't applicable (e.g., docs), provide a clear rationale: Test: markdown file change only
  • NEVER use none or N/A.

• Bug: or Fixes: tag:

  • For Buganizer issues (provided by the user):
    • Use Fixes: <bug_id> for full resolution.
    • Use Bug: <bug_id> for partial/tracking.
    • Use the integer ID only (e.g., 484057256). Do not include the b/ prefix.
  • Omit if there is no bug.

• Relnote: tag:

  • Required for changes in release artifacts (source files under src/main/, src/commonMain/, or src/androidMain/, excluding buildSrc/).
  • This must be a one-sentence description of the public API change or observable behavior change to a library. Note that relnotes must be specific about the observable changes from the CL that a developer may see.
  • Format: Relnote: "Developer-friendly release note" (quotes recommended if it has special characters).
  • Omit entirely if not applicable (e.g., tests, tooling, docs).
  • Use Relnote: N/A only to bypass presubmits for minor source-only changes that don't need a public note.

• Change-Id: tag:

  • NEVER generate this tag manually. It is automatically generated by the git commit hook when you first commit.
  • CRITICAL: When amending a commit, you must always preserve the existing Change-Id line.
  • CRITICAL: NEVER MODIFY OR REMOVE THE Change-Id LINE. Altering it will break Gerrit tracking for patchsets.

Sample Commit Message

Here is an example of a complete, correctly formatted commit message:

Fix: Avoid redundant recomposition in LazyColumn animations

This change optimizes LazyColumn to prevent unnecessary recompositions
when item animations are playing. Previously, even if only the offset
of an item was changing due to animation, a full recomposition was
triggered. By separating the animated offset from the layout pass,
we can achieve smoother animations with less overhead.

Test: ./gradlew :compose:foundation:foundation:connectedAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=androidx.compose.foundation.lazy.LazyColumnAnimationTest
Relnote: Improved performance of LazyColumn animations by reducing redundant recompositions.
Fixes: 298765432
Change-Id: Iabcdef1234567890abcdef1234567890abcdef12345

5. Commit, Best Practices & Upload

• CRITICAL: NEVER upload or push a CL without explicitly asking the user for permission first.

• Gerrit & Commit Best Practices:

  • One Logical Change Per Commit: Each Gerrit change should represent a single, complete logical change. Avoid creating multiple local commits for a single feature or bug fix.
  • Addressing Review Feedback: If you need to address review feedback, fix presubmit failures, or make minor adjustments, do not create a new commit.
  • Use git commit --amend: Always apply fixes directly to the existing commit using git commit --amend. This keeps the Gerrit patchset history clean and keeps all iterations grouped under a single Gerrit Change.
  • Preserve Change-Id: When amending, ensure the Change-Id line at the very end of the commit message is never altered or removed. This is crucial for Gerrit to group your updates as a new patchset under the same CL.
  • Keep Commit Messages Updated: If your changes alter the scope of the CL, update the body/subject of the commit message during the amend process while preserving the Change-Id.

• Commit Commands:

  • New Commit: git commit -m "{commit_message}"
  • Amend/Update Commit: git commit --amend (ensure message is updated but retains the exact Change-Id).

• Upload:

  • Upload to Gerrit:

    repo upload --cbr -t .
    

    Note: --cbr uploads the current branch, -t sets the Gerrit topic to the branch name, and . specifies the project in the current directory.
  • Fallback: If the above command fails or requires interactive prompts, do not attempt to proceed interactively. Report the issue to the user immediately. Agents cannot handle interactive prompts from repo upload.

Once uploaded successfully, present the Gerrit URL to the user and explain that Treehugger presubmit checks will run automatically on the Gerrit change page.