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, tagging a release, or writing a changelog / Play "What's new"
• Publishing a library module (AAR/Maven) that other code depends on
• 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)

2. 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

3. 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"

4. 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

Step 3: Change Sizing

5. Target ~100 lines per commit:

Size	Lines	Review Time	Action
Small	< 50	Minutes	Merge quickly
Medium	50–200	~30 min	Standard review
Large	200–500	Hours	Consider splitting
Too Large	> 500	Days	Must split

6. Split strategies:
   • Refactoring separate from feature work
   • Data layer separate from UI layer
   • Tests in the same commit as the code they test (not separate)

Step 4: Save-Point Pattern

7. Commits as checkpoints:

# Before risky changes:
./gradlew test && git add -A && git commit -m "Checkpoint: working state before refactor"

# Try the change...
# If it breaks:
git revert HEAD  # Undo cleanly

# If it works:
# Continue to next increment

Step 5: Android Versioning

8. Version management in build.gradle.kts:

android {
    defaultConfig {
        // versionCode: monotonically increasing integer
        // Play Store requires each upload to have a higher versionCode
        versionCode = 12

        // versionName: human-readable semantic version
        versionName = "1.2.0"
    }
}

9. Versioning strategy:

versionName: MAJOR.MINOR.PATCH (semantic versioning)
  MAJOR: breaking changes, major redesign
  MINOR: new features, backward compatible
  PATCH: bug fixes, no new features

versionCode: monotonically increasing integer
  Strategy 1: Simple increment (1, 2, 3, ...)
  Strategy 2: Derived from version (10200 for 1.2.0 = major*10000 + minor*100 + patch)
  Strategy 3: Build number from CI (autoincrement)

For an app, MAJOR is a product call (redesign, dropped minSdk); semver is a strict contract only for published library modules (Step 6). Whatever the strategy, versionCode must exceed every value ever uploaded — when switching strategies, offset the new scheme above the last upload.

10. Derive versions from the release tag, don't hand-edit them. CI passes them as Gradle properties; local builds get safe defaults:

// app/build.gradle.kts
val appVersionName = providers.gradleProperty("versionName").getOrElse("0.0.0-dev")
val appVersionCode = providers.gradleProperty("versionCode").map(String::toInt).getOrElse(1)

android {
    defaultConfig {
        versionCode = appVersionCode
        versionName = appVersionName
    }
}

# CI job triggered by pushing tag v1.4.0
VERSION_NAME="${GITHUB_REF_NAME#v}"   # "1.4.0"
IFS=. read -r MAJOR MINOR PATCH <<< "$VERSION_NAME"
VERSION_CODE=$((MAJOR * 10000 + MINOR * 100 + PATCH))   # 10400 (Strategy 1 above)
./gradlew bundleRelease -PversionName="$VERSION_NAME" -PversionCode="$VERSION_CODE"

The tag, the artifact, and the changelog can then never disagree, and two branches can't both hand-bump to the same versionCode.

Step 6: Release & Versioning

11. Tag every release — an immutable, reproducible point in history, on the exact commit that was built:

git tag -a v1.4.0 -m "Release 1.4.0"
git push origin v1.4.0
# Hotfix: fix on main, cherry-pick to release/1.4, tag v1.4.1 there

12. Keep a human changelog. CHANGELOG.md in Keep a Changelog style: newest on top, grouped by Added / Changed / Fixed / Deprecated / Removed / Security, phrased around user impact — not dumped commit messages. Write the entry in the same PR as the change, not reconstructed at release time.

## [1.4.0] - 2026-06-12
### Added
- Share a task list via link
### Fixed
- Recurring tasks drifting by an hour after a timezone change

13. Play Store "What's new" per locale — a short, user-facing summary per release (Play Console limits it to 500 characters per language). Keep the text in the repo so it's reviewed in the PR; the path depends on your upload tool (e.g. distribution/whatsnew/whatsnew-en-US for the r0adkll/upload-google-play GitHub Action, src/main/play/release-notes/en-US/default.txt for Gradle Play Publisher). Automating the upload is ci-cd-and-automation; rollout is shipping-and-launch.

14. Published library modules (AAR/Maven) follow strict semver: removing or changing a public signature — or behaviour consumers rely on (Hyrum's Law, see api-and-interface-design) — is MAJOR; additive API is MINOR; fixes are PATCH. Deprecate in a minor, remove in the next major (see deprecation-and-migration). Catch accidental breaks with the Kotlin binary-compatibility-validator plugin:

// library/build.gradle.kts
plugins {
    id("org.jetbrains.kotlinx.binary-compatibility-validator") version "<latest>"
}

./gradlew apiDump   # writes api/<module>.api — commit it
./gradlew apiCheck  # runs as part of ./gradlew check; fails if the public API drifted from the dump

The .api diff is the review signal: removals or changed signatures mean MAJOR, additions only mean MINOR.

Step 7: Signing Configuration

15. Release signing setup:

// build.gradle.kts
android {
    signingConfigs {
        create("release") {
            storeFile = file(properties["KEYSTORE_PATH"] as String)
            storePassword = properties["KEYSTORE_PASSWORD"] as String
            keyAlias = properties["KEY_ALIAS"] as String
            keyPassword = properties["KEY_PASSWORD"] as String
        }
    }

    buildTypes {
        release {
            signingConfig = signingConfigs.getByName("release")
        }
    }
}

# local.properties (NEVER committed)
KEYSTORE_PATH=../release.keystore
KEYSTORE_PASSWORD=secure_password
KEY_ALIAS=release
KEY_PASSWORD=secure_password

16. Signing rules:
    • Keystore file NEVER in git (store securely, backup separately)
    • Signing credentials in local.properties or CI secrets
    • Use Google Play App Signing for production (Google manages the upload key)
    • Debug keystore is auto-generated (don't commit it)

Step 8: Pre-Commit Checks

17. Before committing:

# Verify staged changes compile and pass tests
./gradlew test && ./gradlew assembleDebug

# Check for secrets
grep -rn "password\|secret\|api_key\|token" --include="*.kt" --include="*.properties" | grep -v "local.properties" | grep -v "test"

Step 9: Git Worktrees for Parallel Work

18. Use worktrees when working on multiple features:

# Create a worktree for a parallel task
git worktree add ../project-feature-b feature/dark-mode

# Work in the worktree independently
cd ../project-feature-b
# ... make changes, commit ...

# Clean up when done
git worktree remove ../project-feature-b

Common Rationalizations

Shortcut	Why It Fails
"I'll squash it all at the end"	Squashed commits lose context. Atomic commits are reviewable and revertable.
"The feature branch will only take a week"	Week-long branches drift from main and create merge conflicts. Use feature flags.
"versionCode doesn't matter"	Play Store rejects uploads with non-increasing versionCode. Plan the strategy early.
"I'll fix the commit message later"	Rewriting history after push is destructive. Write good messages the first time.
"I'll just bump versionName in build.gradle.kts"	Hand edits drift from the tag, and parallel branches collide on the same versionCode. Derive both from the tag/CI.
"It's a small library change, bump the patch"	Diff size is irrelevant; consumers' code is. If apiCheck shows a removed or changed signature, it's a major.
"The changelog is just the commit log"	Commits are for developers; the changelog and "What's new" are for users, curated by impact.
"We'll write the changelog at release time"	By then the impact is reconstructed from memory and half is missing. Write the entry with the change.

Red Flags

• Long-lived feature branches (> 3 days)
• Kitchen-sink commits (> 500 lines, multiple concerns)
• Commit messages that only say "fix" or "update"
• Keystore or signing credentials in git
• versionCode not monotonically increasing
• No CI check on main branch
• Force-push to main
• versionName/versionCode hand-edited in build files, out of sync with the release tag
• A release build with no tag, or a tag not on the commit that was built
• A library module's public API changed with no .api dump diff in the PR, or apiCheck disabled
• A breaking library change shipped under a minor or patch bump
• A release with no CHANGELOG.md entry, or placeholder "What's new" text

Verification

• Feature branches are short-lived (1–3 days)
• Commits are atomic (one logical concern each)
• Commit messages explain why, not what
• versionCode increases with every release
• Signing credentials not in git
• main branch always passes CI
• Pre-commit: ./gradlew test && ./gradlew assembleDebug passes

For every release:

• Release commit tagged (git tag -a vX.Y.Z) and the tag pushed; versionName/versionCode came from the tag/CI, not a hand edit
• CHANGELOG.md has a curated entry for this version, grouped by impact
• Play "What's new" text exists for every shipped locale, within the 500-character limit
• Library modules: ./gradlew apiCheck passes; the bump matches the .api diff (removal/change → major, addition → minor, none → patch)