DEV Community

Mohamed Idris
Mohamed Idris

Posted on

Our Git Branching & Development Workflow — A Practical Guide

#git

Every team needs a branching strategy that balances speed with stability. Here's the workflow our team has settled on — it keeps things predictable without drowning us in process.

The Two Core Branches

We operate with two long-lived branches:

  • production — the source of truth. All feature branches are created from here.
  • development — our shared testing environment. Features land here first for QA before going live.

This separation gives us a clean production branch while still having a space to integrate and test work before it reaches users.

The Standard Feature Flow

Here's how a typical ticket moves through the pipeline:

1. Branch off production
Create a feature branch named after your ticket — e.g., PROJ-123.

2. Develop & commit
Implement the feature. Commit as often as you need.

3. PR into development
Open a pull request targeting development. This is where code review happens. You need at least one approval before merging.

4. Test on development
The developer (and QA, if available) verifies the feature on the dev environment.

5. PR into production
Once QA passes, open a pull request from your original feature branch into production.

6. Final QA on production
After deployment, the ticket moves to QA for a final round of testing on the live environment.

⚠️ Never use the "Resolve conflicts" button on the PR page — it merges the target branch into your feature branch, which is not what you want.

Handling Merge Conflicts

When your feature branch conflicts with development, don't merge dev into your feature branch. Instead:

  1. Pull the latest development.
  2. Create a new branch from it — e.g., PROJ-123-dev.
  3. Merge your feature branch (PROJ-123) into this new branch.
  4. PR this branch into development and close it after merging.

Your original feature branch stays clean for the eventual PR into production.

Commit Messages

Every commit starts with the ticket code:

PROJ-123 - Change 'add-to-cart' button color on PLP
Enter fullscreen mode Exit fullscreen mode

For bigger chunks of work, a summary with sub-items works well:

PROJ-123 / Top Navigation Rework

- Style menu button
- Style search button
- Add logo
- Update country selector dropdown
Enter fullscreen mode Exit fullscreen mode

The key rule: be descriptive. PROJ-123 - Fix bug tells nobody anything. PROJ-123 - Fix cart total not updating on quantity change tells the whole story.

Epic-Based Workflow

For larger features that span multiple tickets, we use an epic branch pattern.

Say you have an epic called "Store Pages" (PROJ-100) with three child tickets (PROJ-101, PROJ-102, PROJ-103). The first developer creates the epic branch (PROJ-100) from production. From there:

  • Each developer branches off the epic branch, not production.
  • Each sub-feature PRs back into the epic branch.
  • The entire epic gets merged into development for testing.
  • Once QA passes, the epic branch goes into production as a single unit.

This keeps related work grouped together and avoids partial features leaking into production.

Does This Follow Convention?

For the most part — yes. This workflow is a variation of the widely-used Git Flow pattern, adapted for simplicity. Here's how it lines up:

  • ✅ Single source of truth — production is always deployable, which aligns with the principle that your main branch should reflect what's live.
  • ✅ Feature branches from the main branch — branching from production keeps features isolated and conflict-free.
  • ✅ Dedicated integration branch — development serves as the integration/staging layer, similar to a develop branch in classic Git Flow.
  • ✅ Code review gating — requiring review before merging into dev is standard practice.
  • ✅ Ticket-based branch naming — tying branches to ticket IDs creates traceability across your project management tool and version control.

One thing to consider as your project matures: PRing directly from a feature branch into production puts more responsibility on dev-environment QA. Introducing a staging branch or grouping tickets into release branches can add an extra safety net — especially after a product goes live and stability becomes more critical.

Key Takeaways

  • Keep production clean — it's your source of truth.
  • Use development as your integration playground.
  • Never resolve conflicts through GitHub's UI button.
  • Name branches after tickets, write descriptive commits.
  • For large features, use an epic branch to group related work.

Simple, predictable, and it scales. That's all a good workflow needs to be.

Top comments (0)