Skip to main content

Branch Structure

Current Structure​

  1. Main Branch:

    • main: Your primary branch that should always be stable and ready for production.

  2. Unit of Work (UOW) Release Branches:

    • Naming: uow-name/release
    • Example: allstar-teambuilding/release or director-dashboard/release
    • Usage: Indicates a release branch for a specific UOW. This branch is merged into main after all tickets under that UOW are complete.

  3. Feature/Issue Branches:

    • Naming: #github_issue_number-small-descriptive-text
    • Example: #1234-fix-user-login
    • Usage: Created for individual tickets/issues. Merged into the corresponding uow-name branch when complete.

Best Practices & Suggestions​

1. Branch Naming Conventions​

  • Use lowercase with hyphens for consistency across all branch types.
  • Ensure release branches follow the /release suffix convention:
    • Example: allstar-teambuilding/release or director-dashboard/release.

2. Pull Request (PR) Best Practices​

  • Feature to UOW: Open PRs from feature branches to the corresponding uow-name branch.
    • PR Title: [#1234] Add new feature
    • Use the GitHub issue number in the PR title for easy tracking.
  • UOW to Main: Once all tickets are merged into the uow-name branch:
    • Open a PR from uow-name/release => main branch.
    • PR Title: UOW: Allstar Teambuilding

3. Branch Protection Rules​

  • Protect the main branch to prevent direct pushes, enforcing code reviews via PRs.
  • Optionally, protect uow-name and uow-name/release branches to ensure peer review before merging.

4. Commit Messages​

  • Follow a consistent commit message format:
    • Example: [#1234] Fix user login flow
    • Format: [Issue Number] Short description of the change

5. Tags and Releases​

  • Use Git tags for marking releases on the main branch.
    • Use semantic versioning (e.g., v1.0.0) for releases that are merged onto main on GitHub.

Example Workflow​

  1. Create Feature Branch:

    git checkout -b "#1234-add-new-feature"

  2. Develop and Commit Changes:

    git commit -m "[#1234] Implemented user authentication flow"

  3. Push Feature Branch & Open PR to UOW Branch:

    git push origin "#1234-add-new-feature"

  4. Merge Feature Branch into UOW Branch (via PR review).

  5. Merge UOW Branch to Release:

    git checkout -b "allstar-teambuilding/release"

  6. Merge Release Branch into Main (once all UOW tickets are complete).

Benefits of This Structure​

  • Scalability: The UOW-based grouping helps manage related features and tickets, making it easier to organize and release code in cohesive chunks.
  • Clarity: Clear branch naming conventions improve team collaboration and communication.
  • Flexibility: Supports parallel development on different UOWs, reducing bottlenecks.
Last updated on by Zach Sedlack