commit-push-pr-workflow

Commit, Push & PR Workflow

Applies to this repo's conventions:

• Do not commit directly to main; use a feature branch and a PR.
• PR/issue titles: English. PR bodies/comments: Simplified Chinese by default (unless the request starts with [EN]).
• Avoid GitHub CLI --body with escaped newlines; prefer --body-file or stdin to prevent literal \\n.

This skill is written to work well on Windows (PowerShell 5.1+). Bash examples are optional.

Branch

• Create a feature branch from main before making changes:
  • git fetch origin --prune
  • git switch main
  • git pull --ff-only
  • git switch -c docs/example-change

Commit

• Confirm required checks have run for the current change scope before committing (record the exact commands).
• Stage intended files only (prefer git add -p).
• Write commit messages using a file (avoid multi--m formatting pitfalls).
• Commit title: prefix: subject or prefix(scope): subject, English only, ideally <= 50 chars (hard wrap <= 72), no trailing period.
• Include a body for non-trivial changes: blank line after title, wrap at 72 columns, include risk/verification notes.

Template (PowerShell, UTF-8 without BOM)

$msg = @'
fix(scope): concise subject

What changed, why, how (if relevant). Wrap at 72 columns.
Risks/side effects if any.
'@

$path = Join-Path $env:TEMP 'commit_msg.txt'
[System.IO.File]::WriteAllText($path, $msg, [System.Text.UTF8Encoding]::new($false))
git commit -F $path
Remove-Item -Force $path

Template (Bash, optional)

cat <<'EOF' > /tmp/commit_msg.txt
fix(scope): concise subject

What changed, why, how (if relevant). Wrap at 72 columns.
Risks/side effects if any.
EOF

git commit -F /tmp/commit_msg.txt
rm -f /tmp/commit_msg.txt

Push

• Push only after checks pass.
• Prefer git push -u origin <branch> for a new branch.
• Avoid force-push.
  • If history rewrite is required (e.g., credential leak removal), confirm explicitly and expect branch rules (e.g., default-branch non-fast-forward) to block force-push unless temporarily adjusted.
  • If git-filter-repo was used: it may remove origin automatically; re-add it before pushing.

Pre-push checklist

• Checks executed (exact commands recorded).
• Commit title/body comply with repo rules.
• User explicitly approved the push (especially for --force).

PR

• Default to a draft PR.

Option A: GitHub CLI (gh)

gh --version
gh auth status

@'
Summary:
- ...

Verification:
- ...
'@ | gh pr create --draft --base main --title "docs: ..." --body-file -

Option B: Browser (no extra tools)

• Push the branch, then open:
  • https://github.com/<owner>/<repo>/pull/new/<branch>

Option C: GitHub API (PowerShell, encoding-safe)

• Prefer using an env var token (do not echo it in logs):
  • $env:GITHUB_TOKEN = '...'

$headers = @{
  Authorization = "token $env:GITHUB_TOKEN"
  'User-Agent' = 'codex-cli'
  Accept = 'application/vnd.github+json'
}

$payload = @{
  title = 'docs: ...'
  head  = '<branch>'
  base  = 'main'
  body  = @"
Summary:
- ...

Verification:
- ...
"@
  draft = $true
} | ConvertTo-Json

$bytes = [System.Text.Encoding]::UTF8.GetBytes($payload)
Invoke-RestMethod -Method Post `
  -Uri 'https://api.github.com/repos/<owner>/<repo>/pulls' `
  -Headers $headers `
  -ContentType 'application/json; charset=utf-8' `
  -Body $bytes

Option D: GitHub API via git credential (PowerShell, no env token)

• If gh is not installed and you do not have GITHUB_TOKEN set, you can reuse the GitHub credential that git already has:

$cred = "protocol=https`nhost=github.com`n`n" | git credential fill
$token = (($cred | Select-String -Pattern '^password=').Line).Substring(9)

$headers = @{
  Authorization = "token $token"
  'User-Agent'  = 'codex-cli'
  Accept        = 'application/vnd.github+json'
}

$payloadObj = @{
  title = 'docs: ...'
  head  = '<branch>'
  base  = 'main'
  body  = "Summary:`n- ...`n"
  draft = $true
}

$json  = $payloadObj | ConvertTo-Json -Depth 5
$bytes = [System.Text.Encoding]::UTF8.GetBytes($json)

Invoke-RestMethod -Method Post `
  -Uri 'https://api.github.com/repos/<owner>/<repo>/pulls' `
  -Headers $headers `
  -ContentType 'application/json; charset=utf-8' `
  -Body $bytes

If editing PR bodies via GitHub API from PowerShell:

• Serialize JSON as UTF-8 bytes (no BOM) to preserve Chinese text reliably.
• Avoid printing tokens or Authorization headers.