| 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.
[!IMPORTANT]
CoG / Isolated Workspace Execution Directive (/google/cog/cloud/...):
In CoG workspaces, standard repo commands and standard repository-modifying git commands are disabled or will fail (fatal: not a git repository).
You MUST ONLY use git citc CLI / API tools when operating inside /google/cog/cloud/...:
| Action | Standard Git Checkout | CoG Workspace (/google/cog/cloud/...) | Notes |
|---|
| Branching | repo start <branch> . | Managed automatically | DO NOT run repo start. |
| Check Status | git status | git citc cli.status | DO NOT run git status. |
| Review Diff | git diff | git citc cli.diff | DO NOT run git diff. |
| Commit / Amend | git commit -m "msg" / --amend | git citc cli.describe -m "msg" | Edits auto-update @. DO NOT run git commit. |
| Upload / Publish | repo upload --cbr -t . | git citc publish | DO NOT run repo upload. |
| Rebase | git rebase <base> | git citc api.call Rebase ... | Rebase via git citc api.call Rebase 'repo_root: "android/frameworks/support" source_node_id: "@" new_base: "<sha>"'. |
NEVER run repo upload, repo start, git status, or git commit in a CoG workspace.
Steps
0. Workspace Preparation & Branching
Ensure you are in frameworks/support/ and on a working branch:
- Standard Git Checkout:
repo start <branch_name> .
- CoG Workspaces:
[!IMPORTANT]
Provision Clean Draft Node BEFORE Editing Files:
At session start or when starting a new CL, CoG working copy @ inherits the local workstation state.
BEFORE making any code modifications or running formatting commands, inspect draft nodes using git citc api.call GetDrafts '' and create a clean draft node off your intended parent node:
git citc api.call NewCommit 'repo_root: "android/frameworks/support" parent_node_id: "<parent_cog_node_id>"'
Parent Selection Rule: Before calling NewCommit, inspect git citc api.call GetDrafts ''. By default, set parent_node_id to the top leaf node of the existing draft stack (the draft node with no child_node_ids). Exception: If the top draft nodes are un-published local duplicate drafts (e.g. copied from cl_session_setup.py sync with needs_publish: true and a Change-Id that is already published on Gerrit), select the highest imported node with an assigned change_number as your parent_node_id instead. Only set parent_node_id to upstream androidx-main if explicitly requested to create an independent, non-stacked CL.
Creating NewCommit upfront ensures your edits accumulate directly on a fresh draft node and prevents NewCommit from wiping out file edits later in the workflow.
1. Analyze Changes (Initial Status)
Identify modified or added files to know what needs formatting and API updates:
- Standard Git Checkout:
git status
- CoG Workspaces:
git citc cli.status and git citc cli.diff
2. Format Code, Run Lint, and Update APIs
- Kotlin Formatting: Run
ktfmt on modified .kt/.ktx files:
./gradlew :ktCheckFile --format --file <file_path>
- Java Formatting: Run
javaFormat on modified Java files:
./gradlew <project>:javaFormat
- Markdown Files: Remove trailing whitespaces in
.md files before committing:
- macOS:
sed -i '' 's/[[:space:]]*$//' <file_path>
- Linux:
sed -i 's/[[:space:]]*$//' <file_path>
- Public API Tracking: If public APIs changed, update signature files:
./gradlew <project>:updateApi
- Lint: Run Lint on the affected module:
./gradlew <project>:lint
Fix issues at call-site (@Suppress("IssueId") // b/BUG_ID), or update lint-baseline.xml via ./gradlew <project>:updateLintBaseline if needed.
3. Review Final Diff
Review final clean state before drafting the commit message:
- Standard Git Checkout:
git diff (or git diff --staged)
- CoG Workspaces:
git citc cli.diff
4. Draft Commit Message & Handle Tags
Write a clear commit message, placing all tags in a contiguous block at the end:
- Subject: Concise imperative summary (<100 characters).
- Body: Explain why changes were made (rationale/background).
Test: tag (REQUIRED): State exact test command (e.g. Test: ./gradlew :compose:ui:ui:connectedAndroidTest -P...) or Test: markdown file change only. NEVER use none or N/A.Bug: / Fixes: tag: Buganizer integer ID (e.g. Fixes: 484057256).Relnote: tag: Required for release artifact changes under src/main/ or src/commonMain/. Use Relnote: "Description" or Relnote: N/A.Change-Id: tag: Generated automatically on first commit in standard Git checkouts via commit-msg hook. In CoG workspaces (git citc), generate and append a fresh Change-Id (Change-Id: I<40_hex_chars>) when drafting a new commit via git citc cli.describe to prevent collisions. NEVER modify or remove Change-Id when amending.
Sample Commit Message
Fix: Avoid redundant recomposition in LazyColumn animations
This change optimizes LazyColumn to prevent unnecessary recompositions
when item animations are playing.
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.
6. Presubmit Triggering & Monitoring
- Pre-Upload Verification:
- Run
./development/validate_changes.sh before uploading.
- Confirm formatting (
ktCheckFile) and public APIs (updateApi).
- Trigger Presubmits:
- Post-Upload Monitoring:
- Use
.agents/skills/manage_commits/scripts/watch_gerrit.py <CL_NUMBER> to poll presubmit results.
