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/&#x3C;owner>/&#x3C;repo>/pull/new/&#x3C;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=httpsnhost=github.comn`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.