git-workflow-and-versioning

Git Workflow and Version Control

Skill Overview

Git workflow and version control provide a comprehensive set of version management best practices to help development teams establish efficient code collaboration processes, covering the entire lifecycle of code management, from commit conventions to version releases.

Applicable Scenarios

1. Daily Code Development and Collaboration

Whenever you need to make code changes, this workflow ensures that every increment is properly committed, reviewed, and versioned. Whether for a solo project or collaboration within a large team, the practices of atomic commits and descriptive messages keep the code history clear and traceable, facilitating code review and troubleshooting.

2. Branch Management and Parallel Development

When handling multiple features, bug fixes, or release management, trunk-based development and short-lived branch principles help teams avoid merge conflicts and keep the mainline deployable at all times. Git worktree can be used to allow multiple AI agents or team members to work in parallel on different branches without interfering with one another.

3. Version Releases and Change Management

When a project has external consumers, Semantic Versioning and tag management provide a clear contract for version releases. Maintaining a changelog helps users understand the impact of each version, while a standardized version bumping strategy ensures that consumers can safely evaluate and perform upgrades.

Core Features

1. Trunk-Based Development and Branch Management

It is recommended to adopt a Trunk-Based Development strategy and keep the main branch deployable at all times. Feature branches should be short-lived and merged within 1–3 days to avoid the merge risks and integration delays associated with long-lived branches. When code must be stabilized for a release while mainline development continues, a release branch may be created, but it should be completed as quickly as possible. Compared with long-lived branches, Feature Flags are preferred for managing unfinished functionality.

2. Atomic Commits and Descriptive Messages

Every successful increment should have its own commit, with a target of approximately 100 lines of code per commit. The principle of atomic commits requires each commit to address only one logical change, avoiding the combination of formatting changes, refactoring, and new features. Commit messages should explain “why,” not merely “what,” use standard type prefixes (feat, fix, refactor, test, docs, chore), and describe the intent and context of the change in the message body.

3. Semantic Versioning

For projects with external consumers, version numbers should follow the MAJOR.MINOR.PATCH Semantic Versioning convention: MAJOR indicates incompatible API changes, MINOR indicates backward-compatible new features, and PATCH indicates backward-compatible bug fixes. A version number is a promise, so code changes must correspond appropriately to version increments. Git tags should be created for releases, making tags the authoritative source of version information rather than manually maintaining version numbers across multiple files.

4. Change Summaries and Review Support

After every modification, provide a structured change summary consisting of three sections: “what changed,” “what was intentionally not touched,” and “potential issues.” This pattern gives reviewers a clear understanding of the scope of the change, helps them identify incorrect assumptions, and demonstrates control over the scope. In particular, the “what was not touched” section demonstrates discipline and the avoidance of unauthorized refactoring.

5. Pre-Commit Hygiene Checks

Before every commit, perform a standard set of checks: review staged changes, ensure that no secrets have been exposed, run tests, and perform linting and type checking. These checks can be automated through Git hooks, such as lint-staged and husky, to prevent non-compliant code from entering the repository. Proper .gitignore configuration also ensures that build artifacts, environment files, or IDE configurations are not accidentally committed.

Frequently Asked Questions

Why is trunk-based development recommended over long-lived feature branches?

Trunk-based development emphasizes keeping the mainline deployable at all times, with feature branches completed and merged within 1–3 days. Long-lived branches are an invisible cost: they accumulate merge risk every day, cause integration delays, and DORA research consistently shows that trunk-based development is associated with high-performing engineering teams. When release stabilization and mainline development must occur simultaneously, a release branch can be used, but it should be completed as quickly as possible. Rather than keeping unfinished functionality on long-lived branches, Feature Flags are preferred for managing the deployment of incomplete features.

How do you determine whether a change should result in a MAJOR, MINOR, or PATCH version bump?

Semantic Versioning decisions are based on changes observable by consumers: PATCH is used for backward-compatible bug fixes, MINOR for backward-compatible new features, and MAJOR for any incompatible API change. The key principle is, “When uncertain whether a change is breaking, assume that it is,” because an unexpected major version bump is less costly than breaking consumers. Note that a behavioral change should be considered a major version bump even if the amount of code involved is small, if it affects behavior on which consumers depend. This relates to Hyrum’s Law: when consumers depend on implementation details, seemingly “small” changes can also be breaking.

What should commit messages contain, and what format is considered standard?

A standard commit message should explain “why,” not merely “what,” using the format <type>: <short description>, optionally followed by a body explaining the intent of the change. Types include feat (new feature), fix (bug fix), refactor (refactoring), test (tests), docs (documentation), and chore (tooling configuration). The message body should explain the reason and context for the change rather than describe obvious differences. For example, feat: add email validation to registration endpoint, accompanied by an explanation such as “Prevents invalid email formats from reaching the database. Uses Zod schema validation...,” is much more useful than simply update auth.ts. Formatting changes should also be separated from behavioral changes, and refactoring should be separated from new features—each type of change should be a separate commit.

How can a team establish Git workflow conventions that suit its needs?

When establishing Git workflow conventions, a team should start from the project’s actual requirements rather than blindly applying an existing framework. Core principles include atomic commits, small and frequent changes, descriptive messages, and a clear branching strategy. If the team already uses Gitflow or another long-lived branch model, these principles can be adapted to fit the existing branching model—commit discipline is more important than the specific branching strategy. The key is to establish consensus: commit messages should explain intent rather than describe differences; branches should have short lifespans; changelogs should be written when changes are made rather than at release time; and every release should be tagged, with the tag serving as the authoritative source of version information. For teams involving AI agents, additional considerations include using worktrees to support parallel development, establishing checkpoint patterns to ensure every step can be rolled back, and defining a clear change-summary template so that AI agents produce structured review information.