Skip to content

flow.md

Latest commit

 

History

History
141 lines (99 loc) · 6.05 KB

flow.md

File metadata and controls

141 lines (99 loc) · 6.05 KB

Bayat Trunk-Based Development

Introduction

This document outlines Bayat's official branching strategy: Trunk-Based Development. This model is designed to promote continuous integration, simplify workflows, and enable rapid, high-quality releases across all project types, from web applications and mobile apps to game development and libraries. It replaces the previously used Git Flow model.

Core Principles

  1. Single Source of Truth: The main branch is the trunk and the single source of truth for the codebase.
  2. Continuous Integration: All developers integrate their work into the main branch frequently. Every commit to main should be production-ready.
  3. Short-Lived Branches: Feature development occurs in short-lived branches that are merged into main as quickly as possible.
  4. Feature Flags: Incomplete features are merged into main but are hidden behind feature flags to avoid impacting production.
  5. Release from Trunk: Releases are cut directly from the main branch, often by creating a tag.

Branch Structure

The Trunk

  • main: This is the trunk. It must always be in a stable, deployable state. Direct commits to main are prohibited; all changes must come through Pull Requests.

Development Branches

  • feature/*: For new features.
  • bugfix/*: For bug fixes.
  • refactor/*: For code improvements.
  • docs/*: For documentation changes.
  • experiment/*: For experiments that might be discarded.

All development branches are short-lived (ideally lasting less than a few days) and are created from the main branch.

Branch Naming Conventions

  • Use lowercase for all branch names.
  • Use hyphens to separate words.
  • Include ticket/issue numbers when applicable.
  • Be descriptive but concise.

Examples:

feature/JIRA-123-user-profile-page
bugfix/login-form-validation
refactor/simplify-database-queries
docs/update-readme

Standard Workflow

  1. Branch Creation:

    • Always branch from the latest version of main.
    • Command: git checkout main && git pull && git checkout -b feature/your-feature-name

  2. Development:

    • Commit frequently with clear, descriptive messages.
    • Keep your branch synchronized with main by frequently pulling changes from main into your feature branch. This helps to avoid large merge conflicts later.
    • Command: git pull origin main

  3. Pull Request (PR):

    • When your changes are complete (and ideally small), open a Pull Request to merge your branch into main.
    • The PR should be small, focused, and backed by automated tests.
    • If the feature is not yet complete, it must be hidden behind a feature flag.

  4. Code Review and Merge:

    • The team reviews the PR.
    • Once approved and all CI checks are passing, the branch is merged into main using a squash and merge strategy. This keeps the main branch history clean and linear.
    • After merging, the feature branch should be deleted.

Release Management

Releases are simple and are triggered directly from the main branch.

  1. Decision to Release: When main has the desired set of features and is stable, a release can be made.
  2. Tagging: A new version is created by tagging a commit on the main branch. We use semantic versioning for tags (e.g., v1.2.3).
    • Command: git tag -a v1.2.3 -m "Release version 1.2.3" && git push origin v1.2.3
  3. Deployment: The CI/CD pipeline is triggered by the new tag and deploys the tagged commit to production.

There are no release branches. The main branch is the release branch.

Hotfixes

Hotfixes are handled in the same way as any other bug fix. There are no special hotfix branches.

  1. Create a bugfix/* branch from main.
  2. Implement the fix.
  3. Open a PR, get it reviewed (expedite if necessary), and merge it into main.
  4. Tag a new patch release from main and deploy it.

The Role of Feature Flags

Feature flags are essential for Trunk-Based Development. They allow us to:

  • Merge incomplete features into main without affecting users.
  • Decouple deployment from release. A feature can be deployed to production but kept hidden until it's ready to be released.
  • Perform A/B testing and canary releases.
  • Quickly disable a faulty feature without redeploying.

All new user-facing features should be developed behind a feature flag.

CI/CD Pipeline

A robust CI/CD pipeline is a prerequisite for Trunk-Based Development.

  1. On Feature Branches: For every commit to a feature branch, the CI pipeline should:

    • Run linting and static analysis.
    • Run all unit and integration tests.
    • Build the application.
    • (Optional) Deploy to a temporary preview environment.

  2. On Merge to main: When a PR is merged into main, the pipeline should:

    • Run all the same checks as on the feature branch.
    • (Optional) Run end-to-end tests.
    • Publish a new build artifact.
    • Deploy to a staging environment for final verification.

  3. On Tag: When a new tag is pushed, the pipeline should:

    • Deploy the exact build artifact from the tagged commit to production.

Commit Message Standards

Commit message standards remain the same as before. Refer to the Git Commits Conventions for detailed guidelines.

Conclusion

Trunk-Based Development is a modern, streamlined approach that enables teams to move faster and release more frequently and reliably. By adhering to the principles of continuous integration, short-lived branches, and the smart use of feature flags, we can improve our development workflow across all Bayat projects.

Version History

Version Date Description
2.0.0 2025-09-18 Migrated from Git Flow to Trunk-Based Development
1.0.0 2025-03-20 Initial version (Git Flow)