Branching Strategy

Every piece of work starts with a new branch from master. Think of master as your stable foundation—it's always deployable, always working. When you start new work, you branch off from that stable base, make your changes, and eventually merge back through a pull request.

Master Branch Protection

We protect the code directories on master (backend/, frontend/, tools/). Only members of the Developers team can push changes to those directories. Everyone on the team can push directly to documentation and design directories like project/, design/, and web-docs/.

Developers should use feature branches and pull requests for code changes — that's our workflow convention. Quick doc edits can go directly to master.

Here's how to create a new branch:

git checkout master
git pull origin master
git checkout -b feat/add-user-auth

Now that you've got a branch, let's talk about how to name it.

Branch Types

Every branch name starts with a type prefix that tells everyone what kind of work you're doing:

• feat/ - New features or functionality
• fix/ - Bug fixes
• docs/ - Documentation changes
• style/ - Code formatting (no logic changes)
• refactor/ - Code restructuring (no behavior changes)
• test/ - Adding or modifying tests
• chore/ - Build tools, dependencies, configurations

Branch Naming Format

Now that you know the types, here's how to build a branch name. It's a simple pattern: the type prefix, followed by a brief description of the change:

{type}/{brief-description}

If you're working on a specific feature epic, include the feature ID:

{type}/{feature-id}-{brief-description}

Real examples:

• feat/add-user-authentication - Adding a new authentication system
• feat/FT050-workflow-automation - Feature work tied to epic FT050
• fix/resolve-link-validation - Fixing a bug in link validation
• docs/create-workflow-guide - Adding this guide you're reading
• chore/update-ruby-version - Updating dependencies

Working with Superthread Cards

If your work is associated with a Superthread card, include the card ID in your branch name or PR title. This automatically links your code changes to the project card and updates the card status as work progresses.

Card ID format: ST-XXX (e.g., ST-128)

Where to include it:

• Branch name: feat/ST-128-add-user-auth
• PR title: feat: add user authentication ST-128

Important: Card IDs in the PR description don't trigger automatic linking—they must be in the branch name or PR title.

You can find the card ID in the card header:

With your branch created and named, you're ready to start making changes. But before we get to the code, let's talk about how we write commit messages in the next section.