Git Workflow

Git Workflow

Git workflow for RAG-Challenge. Uses a simplified GitFlow with develop (integration) and main (production).

Rules

• Never push directly to main or develop — all changes via feature branch + PR
• Conventional Commits format in English: type(scope): description
• No AI attribution in commits or PRs (Co-Authored-By, Generated with, etc.)
• Never force push
• Always update CHANGELOG.md under ## [Unreleased] in code PRs

Branch naming

feature/NNN-description   # New functionality (from develop)
fix/NNN-description       # Bug fixes (from develop)
hotfix/NNN-description    # Urgent production fixes (from main)
chore/description         # Maintenance, tooling, config (from develop)
refactor/description      # Restructure without behavior change (from develop)

NNN = zero-padded sequence number (e.g., 016, 040). Get next available from repo.

Commit types

Workflow for a feature/fix

# 1. Start from develop
git checkout develop && git pull origin develop

# 2. Create branch
git checkout -b feature/NNN-description

# 3. Work (TDD: tests first, then implementation)
# ... make changes ...

# 4. Stage and commit
git add <specific-files>
git commit -m "feat(scope): description"

# 5. Push
git push -u origin feature/NNN-description

# 6. Create PR → develop
gh pr create --base develop --title "feat(scope): description" --body "..."

# 7. After CI green + review → merge (squash if many commits)
# 8. Delete branch after merge

OpenSpec integration

For non-trivial changes, use the OpenSpec workflow first:

1. /opsx:propose <change-name> — creates proposal, design, specs, tasks
2. Create branch: git checkout -b feature/NNN-description
3. /opsx:apply — implements tasks with TDD
4. Push, PR, merge
5. /opsx:archive — archives completed change

PR checklist

• Branch naming follows <type>/NNN-description
• Conventional Commits in English
• Tests pass: cd backend && pytest tests/ -v
• Coverage >= 80%
• Lint clean: ruff check backend/app && ruff format --check backend/app
• Type check: mypy backend/app
• CHANGELOG.md updated under ## [Unreleased]
• docs/conversation_log.md updated if AI-assisted session

Releases

• PR develop → main with title release: vX.Y.Z
• Follow Semantic Versioning (MAJOR.MINOR.PATCH)
• Tag on main after merge: git tag vX.Y.Z && git push origin vX.Y.Z
• Promote [Unreleased] to [X.Y.Z] - YYYY-MM-DD in CHANGELOG

Source: erincon01/RAG-Challenge — distributed by TomeVault.