.agent/git_workflow.md

Git workflow (parallel, safe, deadline-optimized)

This repo will have three engineers working in parallel with agents. The workflow exists to prevent integration chaos.

Branch naming (required)

Format: <name>/<short-scope>

Examples:

• niti/env-scaffolding

• deepak/data-pipeline

• divyank/training-grpo

Rules:

• One scope per branch.

• If a branch grows beyond 23 related commits, cut scope or split.

Commit message convention (required)

Use Conventional Commits:

• feat(env): add OpenEnv reset/step

• fix(parser): handle malformed xml without crash

• test(reward): add 5 handcrafted cases

• docs(readme): add demo + wandb links

Rules:

• Short subject, present tense.

• Prefer why over what in body.

Merge policy (hard rules)

• Merge to main only after the relevant tests pass locally:

  • Env changes: test_no_leak.py, test_env_smoke.py, test_action_parser.py

  • Reward changes: test_reward.py + test_no_leak.py

  • Parser changes: test_action_parser.py + test_env_smoke.py

• No merge now, fix later. Under deadline, broken main is a team-wide blocker.

Force-push rules

• Before midnight Saturday: allowed on your feature branches if necessary.

• After midnight Saturday: no force-push to main (ever).

• Prefer no force-push at all; use revert commits if needed.

PR expectations (fast reviews)

Each PR must include:

• 13 sentence summary

• test plan (what you ran)

• risk note (what could break)

If its large, its wrong: split it.

Pre-submission checklist (Sunday)

By 3 PM:

• HF Space live; /health 200; /docs loads

• Blocking tests pass (.agent/test_contracts.md)

• Training artifact exists (plots + wandb link)

• Demo artifact exists (video URL or text trace fallback)

• README links all resolve (Space, notebook, video, wandb, repo)

By 4:30 PM:

• Fresh clone + run instructions work

• Final smoke test: 100 episodes dont crash

• Submission package is complete

CLI-first ops (HF + GCP)

Keep ops repeatable. Prefer CLI over UI clicks.

Hugging Face:

• huggingface-cli login

• huggingface-cli whoami

• Use git-based Space workflow (clone, commit, push) for deploys.

GCP:

• gcloud auth login

• gcloud config set project <PROJECT_ID>

• Use gcloud compute ssh + gcloud compute instances list for VM workflow.

Cross-reference:

• Merge gates: test_contracts.md

• Scope freeze + fallbacks: project_context.md