Commit & PR Conventions

How to commit and open PRs in verl-project/verl-omni. Load this before any commit or PR. The rules here come from AGENTS.md / CLAUDE.md and are enforced by maintainers — breaching them can result in banning.

When to Use

• Any git commit in this repo.
• Any PR creation (including delegated/agent commits).
• Whenever you infer a module/type label for a change.

Step 0: Contribution policy (fail-closed)

Before proposing a PR, run the duplicate-work checks:

gh issue view <issue_number> --repo verl-project/verl-omni --comments
gh pr list --repo verl-project/verl-omni --state open --search "<issue_number> in:body"
gh pr list --repo verl-project/verl-omni --state open --search "<short area keywords>"

• If an open PR already addresses it → do not open another.
• If your approach differs materially → explain the difference in the issue.
• No low-value busywork PRs (single typo, one style tweak, one mutable default). Mechanical cleanups are acceptable only bundled with substantive work.
• If the work is duplicate/trivial → stop and report what's missing.

PR title format

[{modules}] {type}: {description}

• modules (comma-separated if several). The gate is tests/special_sanity/check_pr_title.py, not AGENTS.md — it accepts the official AGENTS.md set (vllm_omni, diffusion, omni, rollout, trainer, reward, model, algo, fsdp, ray, worker, data, cfg, ckpt, doc, ci, tests, docker, misc) plus training_utils, single_controller, recipe, perf, env, tool. Prefer the official set; the extras are real (recipe for examples/ work, perf for perf changes). Anything outside the validator's list fails the check.
• type: feat, fix, refactor, chore, test.
• [BREAKING] if it breaks any API (CLI args, config, signatures) — placed immediately before the module bracket: [BREAKING][cfg] refactor: ..., not [cfg] [BREAKING] ... (the validator only strips a leading [BREAKING]).
• For a stacked/multi-part PR series, prefix [N/N] (single digits only), e.g. [1/N][omni] feat: .... Combined with [BREAKING] the order is [N/N][BREAKING][module].

Module inference from changed paths

Title examples

[reward] feat: add pickscore visual reward
[diffusion, cfg] feat: add teacher-anchored distillation losses for OPD
[omni] fix: correct attention mask for Qwen3-Omni text+image inputs
[tests] test: cover qwen-image DPO adapter guidance branching on CPU
[BREAKING][cfg] refactor: rename guidance_scale to cfg_scale

Real history to match style: [trainer, algo, cfg] feat: ..., [diffusion, cfg, tests] feat: ..., [1/N][omni] feat: ....

Commit messages

Body explains why, not what. Wrap ~72 chars. For AI-assisted commits, add an explicit disclosure line in the body and attribution trailers (this is the actual repo convention — see recent history):

[reward] feat: add pickscore visual reward

Add a PickScore-based scorer routed via default_compute_score_image so
flow-GRPO runs can optimize human-preference reward.

AI assistance (<your tool name>) was used for this change.

Co-authored-by: <your tool name>
Signed-off-by: Your Name <your.email@example.com>

The Co-authored-by trailer names the assisting tool actually used — substitute your own tool name, do not copy Claude Code verbatim unless you are Claude Code. Signed-off-by with a real name/email is required.

PR description (AI-assisted work — mandatory)

The PR body must include:

1. Why this is not duplicating an existing PR (cite your Step 0 checks).
2. Test commands run and their results.
3. A clear statement that AI assistance was used.
4. A note that a human submitter has reviewed every changed line — pure code-agent PRs are not allowed.

Pre-commit

Ensure hooks pass before committing (pre-commit install once). If you touched config dataclasses, run scripts/generate_trainer_config.sh and commit the regenerated _generated_*.yaml (see config rule).

Common Mistakes

• ❌ Title with a module not in check_pr_title.py, or an invalid type.
• ❌ [BREAKING] after the module bracket ([cfg] [BREAKING]) instead of before it.
• ❌ Opening a PR without the duplicate-work checks.
• ❌ Omitting the AI-assistance disclosure or trailers.
• ❌ Committing a stale _generated_*.yaml.