docs: expand contributing guide with branching and commit examples

- document trunk-based branching with squash-merge convention
- require a benchmark section for performance-affecting commits
- add real commit examples with and without benchmark evidence

CONTRIBUTING.md

@@ -67,8 +67,37 @@ type: short description (~50 chars)
 
 - **Type** must be one of: `fix`, `feat`, `chore`, `docs`, `refactor`, `perf`, `test`, `style`, `ci`, `build`, `revert`.
 - **Subject line** ends with no period.
-- **Body** uses bullet points starting with `-`.
+- **Body** uses bullet points starting with `-`, one bullet per line, no wrapping.
 - No `(scope)` parentheses.
+- Performance-affecting changes (`perf`, and `refactor`/`feat` that move numbers) must add a `Benchmark:` section: one line stating the environment (GPU, dtype, model, relevant switches, measurement method), then one `-` bullet per data point in the form `old -> new unit (ratio, +-%)`.
+
+### Example: regular commit
+
+```
+fix: keep async rollouts version-consistent
+
+- serialize shared-model optimizer updates with generation
+- reject future or over-lagged rollout results after asynchronous scoring
+- close cache publication races
+- persist policy versions in online checkpoints
+```
+
+### Example: performance commit with Benchmark section
+
+```
+refactor: standardize packed 3d inference
+
+- keep training attention on dense 4d tensors
+- use packed 3d tensors with KV cache for inference
+- extend CUDA rotary embedding to packed 3d inputs
+- adapt torch, CUDA and FlashAttention backend dispatch
+
+Benchmark: NVIDIA L20, BF16, 1B model, paged KV cache, CUDA Graph, prompt 512, generation 128 (median of 3 alternating runs)
+- batch 1: 234.5 -> 242.6 tok/s (1.034x, +3.4%)
+- batch 8: 1243.1 -> 1286.6 tok/s (1.035x, +3.5%)
+```
+
+Both examples are real commits from this repository (`git show` them to verify formatting).
 
 ## Common Issues
 
@@ -79,6 +108,15 @@ type: short description (~50 chars)
 | Pre-commit check script fails | Dependency install, tests, or lint failed | Fix the failing step; use `--skip-deps` only when dependencies are already installed |
 | Tests fail with tempdir left | Test crash | Clean `%TEMP%` manually |
 
+## Branching
+
+- **Trunk-based**: `main` is the only long-lived branch and must stay releasable at all times. There is no `develop` or long-lived release branch — releases are cut by pushing a `v*` tag, which triggers `release.yml` to build wheels.
+- Branch from the latest `main` and keep branches short-lived; delete them after merge.
+- Name branches after the commit type: `feat/<slug>`, `fix/<slug>`, `perf/<slug>`, `docs/<slug>` — e.g. `feat/paged-cache-settings`, `fix/moe-routing-consistency`.
+- Rebase onto `main` before opening a PR and again whenever conflicts appear. Force-pushes are acceptable on your own feature branches only — never on `main`.
+- PRs are **squash-merged**: the PR title becomes the commit subject, so write PR titles in the exact commit style (`type: subject`). The individual branch commits are discarded.
+- External contributors work from forks; every PR must pass CI (`lint`, `test (3.12)`) and receive at least one review before merge.
+
 ## Submitting Changes
 
 1. Fork the repo.