Skip to main content

Branching and Versioning Strategy

This document outlines the branching model and versioning scheme for the AllMyChats project.

Branching Strategy: GitHub Flow​

We use GitHub Flow, a simple and effective branching model ideal for continuous deployment.

Branch Types​

1. Main Branch (master)​

  • Purpose: Production-ready code
  • Protection: Protected branch with required reviews
  • Deployment: Automatically deploys to production
  • Rules:
    • No direct commits allowed
    • All changes via Pull Requests
    • Requires passing CI/CD checks
    • Requires at least 1 approval

2. Feature Branches (feature/*)​

  • Naming: feature/descriptive-name
  • Examples:
    • feature/whatsapp-integration
    • feature/user-authentication
    • feature/payment-flow
  • Lifecycle:
    1. Branch from master
    2. Develop and commit changes
    3. Open PR to master
    4. Review, test, merge
    5. Keep (Default)/Delete after merge
  • Best Practices:
    • Keep branches short-lived (1-3 days ideal)
    • Commit often with clear messages
    • Sync with master regularly
    • Use conventional commit format

3. Hotfix Branches (hotfix/*)​

  • Naming: hotfix/issue-description
  • Example: hotfix/payment-webhook-crash
  • Purpose: Urgent production fixes
  • Lifecycle:
    1. Branch from master
    2. Fix the issue
    3. Fast-track PR review
    4. Merge and deploy immediately
    5. Delete after merge

Workflow​

master (protected)
  ↓
  └─→ feature/new-feature
       ↓ (develop)
       ↓ (commit)
       ↓ (push)
       └─→ Pull Request → Review → Merge → Delete
            ↓
          master (deploy)

Versioning Strategy: Semantic Versioning​

We follow Semantic Versioning 2.0.0 with named releases.

Version Format​

MAJOR.MINOR.PATCH
  • MAJOR: Breaking changes (incompatible API changes)
  • MINOR: New features (backwards-compatible)
  • PATCH: Bug fixes (backwards-compatible)

Examples​

  • 0.1.0 → 0.1.1 - Bug fix
  • 0.1.1 → 0.2.0 - New feature
  • 0.2.0 → 1.0.0 - Breaking change or first stable release

Pre-release Versions​

For pre-release versions, append a hyphen and identifier:

  • 1.0.0-alpha.1 - Alpha release
  • 1.0.0-beta.1 - Beta release
  • 1.0.0-rc.1 - Release candidate

Named Releases​

Each major/minor release gets a code name for marketing and communication:

Format: [Version] - "[Descriptive Name]"

Examples:

  • v1.0.0 - "Genesis" - First stable release
  • v1.1.0 - "Swift" - Performance improvements
  • v2.0.0 - "Phoenix" - Major redesign

Naming Guidelines:

  • Choose memorable, positive names
  • Reflect the release's key theme or feature
  • Can use: animals, celestial objects, mythology, nature
  • Keep it professional and brand-appropriate

Commit Message Convention​

We use Conventional Commits for automated changelog generation.

Format​

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

<body>

<footer>

Types​

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, no logic change)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Adding or updating tests
  • build: Build system or dependency changes
  • ci: CI/CD configuration changes
  • chore: Other changes (maintenance)
  • revert: Reverting a previous commit

Examples​

feat(auth): add Google OAuth integration

feat(whatsapp): implement message parsing and analysis
- Parse WhatsApp chat exports
- Extract metadata and statistics
- Support multiple chat formats

fix(payment): prevent duplicate subscription charges

fix(ui): correct theme toggle persistence
Closes #123

BREAKING CHANGE: changed authentication API endpoints

Scope Examples​

  • auth - Authentication
  • payment - Payment processing
  • ui - User interface
  • db - Database
  • api - API endpoints
  • whatsapp - WhatsApp integration

Release Process​

1. Prepare Release​

# Ensure you're on master and up to date
git checkout master
git pull origin master

# Run tests and linting
npm run lint:all
npm test

# Decide version bump (patch/minor/major)
# This will update package.json and create a git tag
npm run release:patch   # 0.1.0 → 0.1.1
npm run release:minor   # 0.1.0 → 0.2.0
npm run release:major   # 0.1.0 → 1.0.0

2. Review and Edit​

The release script will:

  • Bump version in package.json
  • Generate/update CHANGELOG.md
  • Create a git tag
  • Commit changes

Review the generated changelog and edit if needed.

3. Push Release​

# Push commits and tags
git push origin master --follow-tags

4. Create GitHub Release​

  1. Go to GitHub repository
  2. Click "Releases" → "Draft a new release"
  3. Select the created tag
  4. Add release title: v[VERSION] - "[NAME]"
  5. Copy relevant changelog section
  6. Mark as pre-release if applicable
  7. Publish release

5. Deploy​

The CI/CD pipeline will automatically deploy to production when the release is published.

Branch Protection Rules​

Setting Up Branch Protection on GitHub​

After merging this strategy, configure branch protection for master:

Steps:

  1. Go to GitHub repository Settings
  2. Navigate to Branches → Add branch protection rule
  3. Branch name pattern: master
  4. Enable the following:
    • ✅ Require pull request reviews before merging
      • Required approvals: 1
    • ✅ Require status checks to pass before merging
      • Required checks: lint, type-check, test, build
    • ✅ Require conversation resolution before merging
    • ✅ Require linear history (no merge commits)
    • ✅ Do not allow bypassing the above settings

Best Practices​

Branching​

  1. Keep branches focused: One feature/fix per branch
  2. Update regularly: Sync with master often to avoid conflicts
  3. Delete merged branches: Keep repository clean
  4. Use descriptive names: feature/add-user-analytics not feature/updates

Commits​

  1. Commit often: Small, logical commits are easier to review
  2. Write clear messages: Follow conventional commit format
  3. Reference issues: Use Closes #123 or Fixes #456
  4. Don't commit secrets: Use environment variables

Pull Requests​

  1. Provide context: Clear title and description
  2. Keep PRs small: Easier to review and merge
  3. Request specific reviewers: Get the right eyes on the code
  4. Respond to feedback: Address comments promptly
  5. Test before requesting review: Ensure CI passes

Versioning​

  1. Document breaking changes: Always note in BREAKING CHANGE footer
  2. Follow semver strictly: Don't confuse users with wrong increments
  3. Test before releasing: Run full test suite
  4. Write good release notes: Help users understand what changed

Quick Reference​

Create Feature Branch​

git checkout master
git pull origin master
git checkout -b feature/descriptive-name

Commit Changes​

git add .
git commit -m "feat(scope): add new feature"

Open Pull Request​

git push origin feature/descriptive-name
# Then open PR on GitHub

Release​

# On master branch
npm run release:patch  # or minor/major
git push origin master --follow-tags

Tools and Automation​

  • Husky: Git hooks for pre-commit checks
  • Lint-staged: Run linters on staged files
  • Conventional Commits: Enforced commit message format
  • Standard Version: Automated versioning and changelog
  • GitHub Actions: CI/CD automation

Troubleshooting​

Commit Message Rejected​

Problem: commitlint rejects your commit with error like "type may not be empty"

Solution:

# Check the error message
# Fix your commit message to match conventional format
git commit --amend -m "feat(scope): correct message"

Common errors:

  • type may not be empty → Missing type (feat, fix, etc.)
  • type must be lower-case → Use lowercase (feat not FEAT)
  • subject may not be empty → Missing description after colon

Failed CI Checks​

Problem: GitHub Actions CI checks fail

Solution: Run checks locally before pushing

npm run lint:all    # Runs type-check, lint, and format check
npm test            # Runs all tests
npm run build       # Ensures code builds

Merge Conflicts​

Problem: Conflicts when merging or updating branch

Solution: Update your branch with latest master

git checkout master
git pull origin master
git checkout feature/your-branch
git merge master
# Resolve conflicts in your editor
git add .
git commit

Prevention: Regularly sync your feature branch with master to minimize conflicts.

Questions?​

For questions about the branching or versioning strategy, please:

  1. Check this document first
  2. Review the Architecture documentation for technical details
  3. Ask in team chat
  4. Open a discussion on GitHub

Action Items for Setup​

After setting up this strategy, complete the following tasks:

1. Set Up Branch Protection Rules on GitHub​

Priority: High Time: 5 minutes

  1. Go to your GitHub repository
  2. Click Settings → Branches
  3. Click Add branch protection rule
  4. Configure as detailed in Branch Protection Rules section above
  5. Save the rule

Why: Prevents accidental direct commits to master and enforces code review.

2. Test the Commit Message Validation​

Priority: Medium Time: 2 minutes

Try making a test commit to verify commitlint is working:

# This should FAIL
git commit -m "test commit"

# This should SUCCEED
git commit -m "test: verify commitlint setup"

If the first commit succeeds, the git hook may not be installed. Run:

npm install
npx husky install

3. Test the Release Process (Dry Run)​

Priority: Medium Time: 3 minutes

Test the release automation without making actual changes:

git checkout master
git pull origin master
npm run release:dry-run

Review the output to ensure it correctly analyzes commits and would generate appropriate changelog entries.

4. Configure GitHub Actions Secrets (If Needed)​

Priority: Low Time: 5 minutes

If you plan to use the automated release workflow:

  1. Go to GitHub repository Settings → Secrets and variables → Actions
  2. Verify GITHUB_TOKEN is available (it's automatic)
  3. Add any additional secrets needed for deployment

5. Share Documentation with Team​

Priority: Low Time: 10 minutes

  1. Share this branching strategy with your team
  2. Review the strategy in a team meeting
  3. Ensure everyone understands conventional commit format
  4. Consider adding commit message examples to your team wiki

6. Create Your First Release (When Ready)​

Priority: Low Time: 10 minutes

When you're ready to create the first official release:

  1. Ensure all changes are merged to master
  2. Run npm run release:minor (to create v0.1.0 or bump to next version)
  3. Review the generated CHANGELOG.md
  4. Push: git push origin master --follow-tags
  5. Create a GitHub Release with a named version (e.g., "v0.1.0 - Genesis")

Note: Items 1-3 should be completed immediately after setup. Items 4-6 can be done at your convenience.