TheRock/rocm-systems/projects/rocprofiler-compute/.ai/rules/commit-workflow.md

Commit Workflow

Follow this methodology precisely when creating git commits to produce clean, reviewable commits.

Workflow

1. Assess changes

Run these commands in parallel to understand the current state:

• git status (never use -uall flag)
• git diff and git diff --staged to see staged and unstaged changes
• git log --oneline -10 to understand the repo's commit message style

2. Identify the correct files to stage

• Only stage files relevant to the logical change. Prefer git add <file1> <file2> over git add -A or git add ..
• Never stage files that contain secrets (.env, credentials, tokens, etc.).
• Never stage unrelated modifications (e.g., dirty submodules, editor configs).

3. Draft the commit message and confirm with user

Draft a commit message following the repo's conventions. Present it to the user and wait for approval before proceeding. Do NOT commit without confirmation.

Commit message rules for this repo:

• First line: concise summary under 72 characters
• Body: explain the "why", not the "what" — the diff shows the what
• Separate logical points as bullet list items
• Highlight bugfixes explicitly and distinctly from feature changes
• Keep descriptions concise — one to two lines per point, no verbose paragraphs
• Do not include refactoring commentary that is obvious from the diff
• If referencing another project's code as inspiration, keep it to a one-liner
• End with: Co-Authored-By: <AI model name or IDE name>

Tone guidelines (learned from user):

• Do not complain about previous behavior. Describe what the change does, not what was wrong before.
• Be concise. Three bullet points are better than six.
• Only highlight changes that a reviewer needs to know: bugfixes, new features, and notable design decisions.

4. Create the commit

• Use a HEREDOC to pass the commit message to avoid shell escaping issues:

git commit -m "$(cat <<'EOF'
[rocprofiler-compute] Your title here

- Bullet point one
- Bullet point two

Co-Authored-By: <AI model name or IDE name>
EOF
)"

5. Handle pre-commit hooks

• If pre-commit hooks fail (e.g., ruff, formatting), read the output to understand what was auto-fixed or what needs manual fixing.
• Re-stage the fixed files with git add <fixed-files>.
• Create a NEW commit — never use --amend after a hook failure, as the original commit did not succeed and amending would modify the previous commit.
• Repeat until all hooks pass.

6. Verify success

• Run git log --oneline -3 to confirm the commit landed correctly.
• Run git status to confirm a clean working tree (for staged files).

Branch safety

• Never commit directly to develop and rocprofiler-compute-develop
• Always check current branch and apply commit over there, unless user specifies another branch
• If a commit was accidentally made on the wrong branch, move it:
  1. git branch <correct-branch> (create branch at current HEAD)
  2. git reset --hard HEAD~1 (reset the wrong branch back)
  3. git checkout <correct-branch> (switch to the correct branch)

What NOT to do

• Do not use --no-verify to bypass hooks.
• Do not use --no-gpg-sign to disable commit signing to remote unless explicitly asked.
• Do not use --no-verify or --no-gpg-sign to bypass hooks.
• Do not create empty commits.
• Do not batch multiple unrelated changes into one commit.