Skip to main content

How We Use Git

The Web Team adheres to a trunk-based development flow in git.

This approach emphasizes simplicity, swift iteration, and frequent deployments.

Key Concepts​

The main Branch​

  • The main, central hub of our codebase.
  • Branch off of this; merge into it; tag releases on it.
  • main should always be deployable.

No develop, release/XX, etc. Branches​

All changes are made directly to scope-specific branches, and merged back into main via Pull Requests.

Examples of branch prefixes:

  • feature/
  • fix/
  • chore/
  • tweak/
  • hotfix/ (sparingly)
  • bucket/ (sparingly)

Frequent, Iterative Deployments​

Our goal is to deploy small, frequent updates to our sites, allowing us to quickly fix issues and roll out improvements.

This approach helps us avoid the risks and complexities of large releases.

No "Big Bangs"​

Large releases, or "Big Bang releases" as 18F calls them, should be avoided as often as possible.

From 18F:

We do not recommend "big bang releases," defined here as when a team works many months on some code with the expectation that it will be "turned on" in a big release event. We recommend, whenever it's possible, rapid release cycles and iteration, coupled with usability research.

Bucket Branches​

Sometimes, "big bang" releases are necessary. In these rare cases, use a bucket/ branch.

For example, a bucket/php-8.2-compat-fixes branch can serve as a collection point for miscellaneous PRs and tweaks that are more easily managed as one "bucket" of work instead of piecemeal.

As the branch name implies, this "bucket" approach is particularly useful for things like PHP version upgrades; the bucket/ branch lets us group a bunch of closely-related changes into one staging deployment for easier coordination with QA, for example.

Workflow Steps​

Create a branch​

  • For every new feature or fix, create a branch off the main branch.

Develop​

Submit a PR​

  • Once development is complete, open a Pull Request against main and request a code review.

Deploy the branch to staging and test​

  • bot deploy <playbook> <branch name> to staging

Merge into main; deploy main to staging and test​

  • bot deploy <playbook> main to staging

Deploy main to production​

  • If all is looking good after the code reviews, staging deployments, and testing, deploy to production!