Git Workflow

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

Branch strategy

Branch	Purpose
main	Production. Protected — only maintainers merge here, which triggers a CI release (semantic-release) and deploy.
dev	Development 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

Type	Bump	Example
fix	patch	fix(api): handle null responses from user endpoint
feat	minor	feat(map): add layer opacity control
perf	patch	perf(viewer): reduce re-renders on tile load
build, ci, docs, refactor, test	no release	docs(readme): update setup instructions
BREAKING CHANGE: in footer	major	feat!: migrate auth to Auth.js

References

• Conventional Commits spec
• Angular commit message guidelines
• First Contributions practice repo

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 change	When
PATCH (for example, 1.0.1)	Bug fixes and performance improvements
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

Contributions target @collabdt/core — the open-source library. To contribute:

1. Fork CollabDigitalTwins/core on GitHub.
2. Clone your fork and install dependencies:

git clone https://github.com/<your-username>/core.git
cd core
yarn install

3. Branch off dev, make your change, and validate it:

yarn build
yarn test:unit
yarn lint

4. Push to your fork and open a pull request against dev. You'll be asked to sign the Contributor License Agreement on your first PR.

No environment files or services are needed — core is a library. See Dev Environment Setup for the full guide.

Related

• Dev Environment Setup
• Contributing