Contributing

See the root contributing guide:

• CONTRIBUTING.md
• CLI Error Style

Local validation checklist

# backend
cd backend/agent
ruff check g_agent tests --select F
pytest -q

# docs
cd ../..
python -m pip install -r docs/requirements.txt
python backend/agent/scripts/generate_cli_docs.py
mkdocs build --strict

# optional: compress oversized tracked images
bash deploy/optimize-images.sh --dry-run

Recommended: enable local git hooks

git config core.hooksPath .githooks
chmod +x .githooks/pre-commit .githooks/pre-push

Maintainer release checklist

Before tagging a release (vX.Y.Z):

1. Update version metadata:
2. backend/agent/pyproject.toml
3. backend/agent/g_agent/__init__.py
4. backend/agent/uv.lock
5. Update release docs:
6. CHANGELOG.md
7. docs/release-notes/vX.Y.Z.md (must exist and be non-empty)
8. Run validation:

cd backend/agent
python -m compileall -q g_agent
ruff check g_agent tests --select F
pytest -q

1. Open PR, merge to main, then push tag:

git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

Notes:

• CI blocks version-bump PRs without non-empty docs/release-notes/vX.Y.Z.md.
• Release workflow publishes GitHub release notes from that file.