Skip to main content

Git Workflow

CDT uses a feature-branch workflow on top of two long-lived branches: dev (integration) and main (production).

Branch strategy​

BranchPurpose
mainProduction. Protected — only maintainers merge here, which triggers a CI release (semantic-release) and deploy.
devDevelopment integration. Feature branches merge here first via reviewed PRs.
feature/*Your work. Branch off dev, then open a PR back into dev.

Branch protection. main and dev are protected. Contributions go through pull requests — direct pushes to main and dev are restricted to maintainers. PRs into dev require maintainer review and approval, and only maintainers promote dev to main.

Creating a feature branch from a GitHub issue​

GitHub lets you create a branch directly from an issue. Once the branch exists, check it out locally:

git fetch origin
git checkout 718-creating-new-api-endpoint

Keeping your feature branch up to date​

Before opening a PR, pull the latest dev into your branch to reduce merge conflicts:

git fetch origin
git merge origin/dev

Commit message convention​

CDT follows the Conventional Commits specification, which semantic-release uses to determine version bumps automatically.

Format​

<type>(<scope>): <short description>

Types and their version impact​

TypeBumpExample
fixpatchfix(api): handle null responses from user endpoint
featminorfeat(map): add layer opacity control
perfpatchperf(viewer): reduce re-renders on tile load
build, ci, docs, refactor, testpatchdocs(readme): update setup instructions
BREAKING CHANGE: in footermajorfeat!: migrate auth to Auth.js

References​

Semantic versioning​

CDT uses semantic-release to automate versioning based on commit messages. It runs in CI when commits land on main or beta.

Version format: MAJOR.MINOR.PATCH

Version changeWhen
PATCH (for example, 1.0.1)Bug fixes, docs, refactors
MINOR (for example, 1.2.0)New backwards-compatible features
MAJOR (for example, 2.0.0)Breaking API changes

How it works​

  1. A maintainer merges a reviewed PR into main with conventional commit messages.
  2. semantic-release runs in CI, determines the version bump from commit types.
  3. A GitHub release is created automatically with a changelog.

See the semantic-release docs for configuration details.

Forking the repository​

The CDT repository is private during the pre-release period. To contribute:

  1. Ask a team lead to invite you as a collaborator (GitHub docs).
  2. Accept the email invitation.
  3. Fork the repo, naming your fork cdt-{initials} (for example, cdt-dp).
  4. Clone your fork:
git clone https://github.com/<your-username>/cdt-<initials>.git
cd cdt-<initials>
  1. Copy the .env file from your team lead into the project root.
  2. Install dependencies and start the dev server:
yarn        # or: npm install
yarn dev    # or: npm run dev