git-workflow-and-versioning

Git Workflow and Versioning

Overview

Trunk-based development: keep main always deployable, use short-lived feature branches (1–3 days), and make atomic commits that address one logical concern. Android versioning requires managing versionCode (monotonic integer for Play Store) and versionName (human-readable semver).

When to Use

• Starting a new feature branch
• Making commits during development
• Preparing a release
• Managing version numbers
• Reviewing branch strategy or merge approach
• Setting up signing configurations

Skip when: The project has an established, documented git workflow.

Core Process

Step 1: Trunk-Based Development

1. Branch strategy:

main (always deployable)
  ├── feature/task-sharing      (1-3 days, then merge)
  ├── feature/dark-mode         (1-3 days, then merge)
  ├── fix/crash-on-empty-list   (hours, then merge)
  └── release/1.2.0             (cut from main, hotfixes only)

1. Branch rules:
   • main is always green (CI passes)
   • Feature branches are short-lived (1–3 days max)
   • Delete branches after merge
   • No long-lived feature branches — use feature flags instead
   • Release branches are cut from main, not from feature branches

Step 2: Atomic Commits

1. Each commit addresses one logical concern:

# GOOD: atomic commits
git commit -m "$(cat <<'EOF'
Add TaskDao with CRUD operations

Room DAO for tasks table with observe, upsert, and delete operations.
Flow-based observation for reactive UI updates.
EOF
)"

git commit -m "$(cat <<'EOF'
Add TaskRepository with offline-first sync

Implements TaskRepository interface. Local Room database is the source
of truth. Remote sync via Retrofit with error handling for network
failures.
EOF
)"

# BAD: kitchen sink commit
git commit -m "Add task feature with database, API, UI, and tests"

1. Commit message format:
   • First line: imperative, under 72 characters ("Add", "Fix", "Update", "Remove")
   • Blank line
   • Body: explain why, not what (the diff shows what)
   • Reference issue numbers: Fixes #42