Skip to content

Git Workflow

Development workflow and Git conventions for Vows Social AI.

Branch Strategy

We use GitHub Flow - a simplified Git workflow optimized for continuous deployment.

Branch Types

Main Branch: - main - Production-ready code - Always deployable - Protected (requires PR + approval) - Auto-deploys to production

Feature Branches: - feature/short-description - New features - fix/short-description - Bug fixes - refactor/short-description - Code improvements - docs/short-description - Documentation - test/short-description - Test additions

Example: 

feature/thompson-sampling
fix/qdrant-connection
refactor/agent-scoring
docs/api-reference
test/orchestrator-unit-tests

Workflow

1. Create Feature Branch

# Update main
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/my-feature

# Push to remote
git push -u origin feature/my-feature

2. Make Changes

# Make your changes
# ...

# Stage changes
git add .

# Commit with conventional commit message
git commit -m "feat: add Thompson Sampling to Orchestrator"

3. Push & Create PR

# Push changes
git push origin feature/my-feature

# Create PR via GitHub CLI
gh pr create --title "Add Thompson Sampling" --body "$(cat <<'EOF'
## Summary
- Implements Beta-Bernoulli Thompson Sampling
- Integrates with Orchestrator Durable Object
- Adds reward update logic

## Test Plan
- [x] Unit tests for Thompson Sampling
- [x] Integration test with Orchestrator
- [x] Manual testing with sample data
EOF
)"

4. Code Review

  • Request review from team member
  • Address feedback
  • Push updates to same branch
  • PR updates automatically

5. Merge

# Once approved, merge via GitHub UI or CLI
gh pr merge --squash --delete-branch

Commit Messages

We follow Conventional Commits specification.

Format

<type>(<scope>): <subject>

<body>

<footer>

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Code style (formatting, missing semicolons)
  • refactor: Code refactoring
  • perf: Performance improvement
  • test: Adding tests
  • chore: Maintenance (deps, config)
  • ci: CI/CD changes

Examples

Feature: 

feat(orchestrator): add Thompson Sampling ranking

Implements Beta-Bernoulli Thompson Sampling for content ranking.
Includes alpha/beta parameter tracking in Durable Object storage.

Closes #123

Bug Fix: 

fix(qdrant): handle connection timeout gracefully

Adds retry logic with exponential backoff for Qdrant connections.
Prevents feed generation failures on transient network issues.

Fixes #456

Documentation: 

docs(api): add Foundation Model API reference

Documents /embed endpoint with request/response examples.

Breaking Change: 

feat(api): update feed response format

BREAKING CHANGE: Feed response now includes agent scores.

Old format:
  { feed: [...] }

New format:
  { feed: [...], metadata: { agentScores: {...} } }

Migration: Update client to handle new format

Pull Request Guidelines

PR Title

Use conventional commit format: 

feat(orchestrator): add Thompson Sampling
fix(quality-guardian): handle missing images
docs: update README with setup instructions

PR Description Template

## Summary
Brief description of what this PR does

## Changes
- Bullet points of key changes
- Keep it concise but informative

## Test Plan
- [x] Unit tests pass
- [x] Integration tests pass
- [x] Manual testing completed
- [ ] Performance tested (if applicable)

## Screenshots/Demos
(If UI changes)

## Related Issues
Closes #123
Relates to #456

## Notes
Any additional context for reviewers

PR Best Practices

  1. Keep PRs small - Easier to review, faster to merge
  2. One concern per PR - Don't mix features and refactors
  3. Update tests - Add/update tests for your changes
  4. Update docs - Keep documentation in sync
  5. Self-review - Review your own PR before requesting review

Code Review

Reviewer Checklist

  • Code follows project style guidelines
  • Changes are well-tested
  • Documentation is updated
  • No obvious bugs or issues
  • Performance considerations addressed
  • Security implications considered

Review Comments

Requesting Changes: 

Could we add error handling here?

The Qdrant connection could fail if the service is down.
Consider adding a try-catch with retry logic.

```python
try:
    results = await qdrant.search(...)
except QdrantConnectionError:
    # Retry or fallback logic

Approving: 

LGTM! 🚀

The Thompson Sampling implementation looks solid.
Tests are comprehensive and performance is good.

Suggesting Improvements (non-blocking): 

Nit: Consider extracting this into a helper function

Not required for this PR, but this logic is repeated 3 times.
Could be cleaner as a reusable function.

Release Process

Versioning

We use Semantic Versioning (semver): - MAJOR.MINOR.PATCH - 1.0.0 → 1.0.1 (patch - bug fix) - 1.0.1 → 1.1.0 (minor - new feature) - 1.1.0 → 2.0.0 (major - breaking change)

Creating a Release

# Tag the release
git tag -a v1.0.0 -m "Release v1.0.0: Initial MVP"

# Push tag
git push origin v1.0.0

# Create release via GitHub
gh release create v1.0.0 \
  --title "v1.0.0 - Initial MVP" \
  --notes "$(cat CHANGELOG.md)"

Changelog

Keep CHANGELOG.md updated with each release:

# Changelog

## [1.1.0] - 2025-10-15

### Added
- Thompson Sampling for feed ranking
- Quality Guardian agent
- Discovery Agent for Instagram

### Fixed
- Qdrant connection timeout handling
- User embedding cold start

### Changed
- API response format for feed endpoint

### Removed
- Deprecated chronological feed

Git Hooks

Pre-commit Hook

Runs linting and type checking:

#!/bin/sh
# .git/hooks/pre-commit

# Run TypeScript type check
npm run type-check

# Run ESLint
npm run lint

# Run Python type check
mypy services/

# Run tests
npm test

Setup Hooks

# Install husky for git hooks
npm install --save-dev husky

# Enable git hooks
npx husky install

# Add pre-commit hook
npx husky add .husky/pre-commit "npm run pre-commit"

Common Tasks

Update from Main

# On feature branch
git checkout feature/my-feature

# Fetch latest
git fetch origin

# Rebase on main
git rebase origin/main

# Force push (if already pushed)
git push --force-with-lease

Resolve Conflicts

# During rebase, if conflicts occur
git status  # See conflicted files

# Edit files to resolve conflicts
# Then:
git add <resolved-files>
git rebase --continue

# Or abort rebase
git rebase --abort

Squash Commits

# Interactive rebase last 3 commits
git rebase -i HEAD~3

# In editor, change 'pick' to 'squash' for commits to squash
# Save and close

# Edit combined commit message
# Save and close

# Force push
git push --force-with-lease

Cherry-pick Commit

# Copy commit from another branch
git cherry-pick <commit-hash>

# Handle conflicts if any
git cherry-pick --continue

CI/CD Integration

GitHub Actions

On Push to Feature Branch: - Run linters - Run tests - Build check

On PR: - Run full test suite - Deploy to preview environment - Run E2E tests

On Merge to Main: - Run tests - Build production bundle - Deploy to production

Example Workflow

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, 'feature/**']
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build

Resources

Questions?