Git Conventions - Tuturuuu Docs

Prerequisite: You should be familiar with basic Git operations and understand the Monorepo Architecture of our codebase.

Overview

Tuturuuu follows standardized conventions for Git commits and branch naming to improve collaboration, automate releases, and maintain a clean, navigable repository history. We use two main specifications:

Conventional Commits for structured commit messages
Conventional Branch for consistent branch naming

These conventions help automate our CI/CD workflows, generate changelogs, and make our development process more efficient.

Conventional Commits

What are Conventional Commits?

Conventional Commits is a specification for adding human and machine-readable meaning to commit messages. It provides a set of rules for creating an explicit commit history, making it easier to write automated tools on top of. The basic structure of a conventional commit is:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

Tuturuuu uses the following commit types:

Type	Description	Example
`feat`	New feature or enhancement	`feat: add dark mode support`
`fix`	Bug fix	`fix: prevent crash when user data is undefined`
`docs`	Documentation changes	`docs: update installation instructions`
`style`	Code style changes (formatting, no code change)	`style: format code with prettier`
`refactor`	Code refactoring	`refactor: simplify authentication logic`
`perf`	Performance improvements	`perf: optimize database queries`
`test`	Add or fix tests	`test: add unit tests for auth middleware`
`build`	Changes affecting build system or dependencies	`build: update dependency to fix security issue`
`ci`	Changes to CI configuration files and scripts	`ci: simplify workflow branch filters`
`chore`	Routine tasks, maintenance	`chore: update package.json metadata`

Scopes

Scopes provide additional context about which part of the codebase is affected. In our monorepo structure, we often use package or app names as scopes:

feat(web): add new dashboard layout
fix(ui): correct button alignment in mobile view
chore(types): update supabase database types

Breaking Changes

Breaking changes must be indicated by adding a ! after the type/scope or by using a BREAKING CHANGE: footer:

feat(api)!: require authentication for all endpoints

BREAKING CHANGE: All API endpoints now require authentication tokens.

Examples

Here are some examples of conventional commits used in our codebase:

feat(web): add new calendar integration
fix(supabase): correct permission issue in auth policy
docs(readme): update development setup instructions
style: apply consistent formatting with prettier
refactor(utils): simplify date formatting functions
perf(queries): optimize workspace user loading
test(auth): add tests for token verification
build(deps): update Next.js to v14
ci(vercel): add automatic preview deployments
chore(release): publish packages

Conventional Branches

What are Conventional Branches?

Conventional Branch refers to a structured naming convention for Git branches that makes it easier to identify branches by type and purpose. The basic structure is:

<type>/<description>

Branch Types

Tuturuuu uses the following branch types:

Type	Description	Example
`main`	Main development branch	`main`
`feature`	For new features	`feature/user-dashboard`
`feat`	Short feature prefix also accepted	`feat/invite-link-permissions`
`fix`	Short bug-fix prefix also accepted	`fix/invite-membership-check`
`bugfix`	For bug fixes	`bugfix/login-error`
`hotfix`	For urgent fixes	`hotfix/security-vulnerability`
`release`	For preparing releases	`release/v1.2.0`
`chore`	For maintenance tasks	`chore/update-dependencies`
`docs`	For documentation-only work	`docs/git-conventions-refresh`
`style`	For formatting or stylistic cleanups	`style/biome-pass`
`refactor`	For internal code restructuring	`refactor/task-query-shell`
`perf`	For performance-focused changes	`perf/workspace-user-search`
`dependabot`	Automated dependency update branches	`dependabot/npm_and_yarn/next`
`claude`	AI-assisted scratch or experimental PR	`claude/rate-limit-audit`

Release Please bot branches are also accepted with the release-please--branches-- prefix. Do not create human-authored branches with that prefix.

Naming Rules

Use lowercase alphanumeric characters and hyphens
Keep names concise but descriptive
Include ticket/issue numbers when applicable
Avoid special characters (except hyphens)

Examples

feature/workspace-sharing
feat/public-course-sharing
fix/file-upload-error
bugfix/auth-vulnerability
release/v2.5.0
chore/update-react-18
docs/git-conventions-refresh
feature/issue-123-user-profile

Merge Commit Exception

Authored commits should follow Conventional Commits. The common exception is a Git-generated merge commit when syncing a long-lived branch, for example:

Merge branch 'main' into feat/studying-platform

Keep that merge summary when the goal is to preserve the branch’s merge history. Use a conventional commit message again for the next authored commit after the merge.

How These Conventions Improve Our Workflow

1. Automated Changelog Generation

Our conventional commits are used to automatically generate changelogs for releases. Different commit types are categorized accordingly:

# Changelog

## Features

- add dark mode support (#123)
- add calendar integration (#124)

## Bug Fixes

- prevent crash when user data is undefined (#125)

## Documentation

- update installation instructions (#126)

2. Semantic Versioning

Conventional commits help determine the next semantic version for packages:

fix: commits trigger a PATCH increment (1.0.0 → 1.0.1)
feat: commits trigger a MINOR increment (1.0.0 → 1.1.0)
Commits with BREAKING CHANGE trigger a MAJOR increment (1.0.0 → 2.0.0)

3. Automated Release PRs And Package Publishing

Release Please reads Conventional Commits from production, updates release-please-config.json packages through .release-please-manifest.json, and opens one combined release PR with package versions and changelogs. Package publish workflows do not generate versions; they publish only after a release-please version bump lands on production. Local manifests keep Tuturuuu workspace dependencies as workspace:*; npm release workflows rewrite the checked-out package manifest with scripts/ci/prepare-npm-package-manifest.js immediately before npm pack so published artifacts contain installable npm version ranges. Package-included file: tarball dependencies, such as @tuturuuu/ui’s vendored SheetJS tarball, stay local in the packed manifest and must not be rewritten to mutable external tarball URLs. Before any build or pack work starts, package workflows run scripts/ci/package-release-readiness.js gate-package-release packages/<name>. The gate checks publishable Tuturuuu workspace dependency versions on npm once, dispatches missing dependency workflows, and exits green without occupying a runner while dependencies are pending. If the related dependency workflow for the same production SHA failed, completed successfully without npm visibility, or cannot be inspected, the gate fails immediately. Publish jobs still wait for their own version to become visible after npm publish, then a separate non-OIDC job dispatches direct dependent package workflows. Workflow-published package manifests must carry provenance-compatible repository metadata for tutur3u/platform; otherwise npm rejects trusted publishes with E422. For example, release-types-package.yaml triggers from production changes to packages/types/package.json: When bringing the generated release PR branch back to main, run bun git-release-please from a clean main checkout. The helper fetches the latest release-please--branches--production branch, merges it without committing, syncs platform-version.txt into the platform badge constant and test expectation, runs bun ff, stages the resolved merge, then runs bun check directly before the merge commit lands. When the staged release merge includes apps/mobile paths, the helper also runs bun check:mobile. If you are already inside a manual merge, run bun release:sync-platform-version to resolve the recurring TUTURUUU_PLATFORM_VERSION conflict before staging the merge.

on:
  push:
    branches: [production]
    paths:
      - "packages/types/package.json"
  # ...

jobs:
  check-version-bump:
    if: github.ref == 'refs/heads/production' && needs.check-ci.outputs.should_run == 'true'
    # ...

4. Better Code Reviews

With conventional commits and branches, it’s easier to understand the purpose of a pull request at a glance:

A PR from feature/user-dashboard with commits like feat: add user stats widget clearly indicates a new feature
A PR from bugfix/auth-issue with commits like fix: prevent token expiration error indicates a bug fix

Conventional branch names make it easier to navigate the repository history and find specific changes. For example:

# Find all feature branches
git branch --list "feature/*"

# Find branches related to authentication
git branch --list "*auth*"

Tools and Enforcement

We use a dedicated CI/CD check to enforce our Git conventions:

Branch Naming Check

We use a GitHub Action workflow to verify that branch names follow our convention:

name: Branch Name Check

on:
  push:
    branches-ignore:
      - main
      - production

jobs:
  check-branch-name:
    name: Check branch name
    runs-on: ubuntu-latest
    steps:
      - name: Check branch name
        run: |
          BRANCH_NAME=${GITHUB_REF#refs/heads/}
          if ! [[ $BRANCH_NAME =~ ^(feature|feat|fix|bugfix|hotfix|release|chore|docs|style|refactor|perf|dependabot|claude)/.+|^release-please--branches--.+ ]]; then
            echo "❌ Branch name '$BRANCH_NAME' doesn't follow the conventional branch format."
            echo "Branch name should be in format: type/description"
            echo "Allowed types: feature, feat, fix, bugfix, hotfix, release, chore, docs, style, refactor, perf, dependabot, claude"
            echo "Release Please bot branches are also allowed with the release-please--branches-- prefix."
            exit 1
          else
            echo "✅ Branch name follows convention: $BRANCH_NAME"
          fi

Best Practices

Writing Good Commit Messages

Use the imperative mood (“add” not “added” or “adds”)
Keep the description in lowercase to match the repository’s observed convention (for example, feat(backend): migrate nova team read)
Do not end the description with a period
Keep the description under 72 characters
Use the body to explain the what and why, not the how

Example of a well-formatted commit:

feat(auth): add multi-factor authentication support

Implement TOTP-based multi-factor authentication to improve security.
The implementation follows the RFC 6238 standard.

Closes #123

Coordinating Commits In Shared Checkouts

When multiple agents or humans may commit in the same checkout, use the commit window before changing the staged set. The lock is advisory and lives under the ignored tmp/agent-coordination/ directory, so it protects the Git index and commit operation without becoming part of a commit. Claims default to 10 minutes and may only be 5-10 minutes, so claim only when ready to stage, inspect, and commit. This coordination is per-checkout and harness-agnostic. The commit window and the tmp/agent-coordination/ notes both live in the working directory, so they coordinate every agent or human sharing one checkout — parallel Codex or Claude Code sessions, background tasks, and same-directory subagents — regardless of which tool they run under. A separate git worktree has its own lock file, its own notes, and its own Git index, so the window does not span worktrees; separate worktrees stay isolated by being on different branches and integrate through the shared remote instead. In a hot shared checkout, commit your owned paths promptly in small scoped commits: a large unstaged set can be discarded by a concurrent rebase, reset --hard, checkout, or stash from any agent or human. (bun git-sync is isolated and safe; manual destructive Git is not.)

bun git-commit-window status
bun git-commit-window claim --owner "<agent/task>" --scope "type(scope): subject"
git add path/to/file-a path/to/file-b
git diff --cached --stat
git diff --cached --name-only
git commit -m "type(scope): subject"
bun git-commit-window release --token <token>

If another agent owns the window and it is appropriate to wait, use wait. The command sleeps until the active lock is released or expires, then claims the window before reporting that it is safe to proceed. The waiting period can be longer than the claim TTL, but the claimed window remains capped at 10 minutes:

bun git-commit-window wait --owner "<agent/task>" --scope "type(scope): subject"

Use --allow-staged only after inspecting existing staged files. The commit window does not grant ownership of files or permission to stage unrelated paths. Existing staged files are owned by the staging agent or coordinator until explicitly reassigned. If a file appears as MM, both its staged and unstaged diffs need owner review before commit. Let commit hooks run by default. This is a proof-gated no-verify path: use git commit --no-verify only when the current agent can prove its exact staged paths would pass the checks normally covered by bun check. The proof packet should include reviewed git status --short, git diff --cached --stat, and git diff --cached --name-only output; the touched files or narrow path group; the separated checks that covered each affected bun check component; any skipped components with path-based rationale; unrelated dirty files excluded from the claim; and bun check:mobile coverage when apps/mobile is touched. If ownership is unclear, proof is incomplete, or the check mapping is uncertain, do not bypass the hook. Commit hooks and repo checks can read the whole worktree, including files owned by other agents. If they fail on unrelated dirty files, release the commit window and report the blocker instead of formatting, fixing, staging, or committing those files for convenience. Only the staged-set owner may use the proof-gated no-verify path, and only with exact-path evidence for the staged files.

Branch Management

Create branches from the latest main branch
Keep branches focused on a single task or issue
Regularly rebase long-lived branches on main to avoid merge conflicts
Delete branches after they’ve been merged

Synchronizing Release Branches

Use the root command below when production should point at the same commit as main:

bun git-sync

The command fetches origin, creates a temporary detached worktree, refreshes main, and fast-forwards production to the current main commit from that temporary worktree before pushing those branches. It finishes by fetching again and verifying that local and remote main and production both resolve to the same commit. The checkout you started from is left untouched, so uncommitted work on another branch can keep running while the release refs are synchronized. If a branch that needs to move is already checked out in another worktree, Git will refuse to force-update that branch. Switch that worktree away from the branch or update it manually, then rerun bun git-sync. bun git-sync does not create commits for you. Commit all intended changes on main first; if production contains commits that are not already in main, reconcile the branch manually before rerunning the command. Use --only-branch to update one active sync branch while leaving the other untouched:

bun git-sync --only-branch production

main is still refreshed locally as the source commit, but only production is fast-forwarded and pushed. Use --only-branch main when you only want to pull and push main. The retired staging branch is no longer a supported --only-branch target. The Supabase staging environment still exists, but its workflow is driven from main. Use --current-branch or -c when main and production should move to the latest commit on the branch you currently have checked out instead of latest origin/main:

bun git-sync --current-branch
bun git-sync -c

Current-branch mode still uses a temporary detached worktree, leaves the checkout you started from untouched, and only moves the selected sync branches. It does not push the source branch unless the source branch is itself one of the selected sync branches, such as running from main. Combine -c with --only-branch when only one long-lived branch should move to the current checkout’s commit:

bun git-sync -c --only-branch production

Use --no-push for local-only synchronization:

bun git-sync --no-push
bun git-sync --only-branch production --no-push
bun git-sync -c --no-push

With --no-push, the command fetches, pulls with --ff-only, and fast-forwards the selected local branches, but it never pushes to origin. Final verification checks local refs only.

Pull Request Workflow

Create a branch with the appropriate type based on the work
Make commits using conventional commit messages
Push the branch and create a pull request
Use conventional commit style for the PR title
After approval and merge, delete the branch

Conclusion

Following these Git conventions helps us maintain a clean, understandable repository history, automate release processes, and improve collaboration across the team. By standardizing both commit messages and branch names, we create a more efficient development workflow. For more information, refer to the official documentation for Conventional Commits and Conventional Branch.

​Overview

​Conventional Commits

​What are Conventional Commits?

​Types

​Scopes

​Breaking Changes

​Examples

​Conventional Branches

​What are Conventional Branches?

​Branch Types

​Naming Rules

​Examples

​Merge Commit Exception

​How These Conventions Improve Our Workflow

​1. Automated Changelog Generation

​2. Semantic Versioning

​3. Automated Release PRs And Package Publishing

​4. Better Code Reviews

​5. Simplifying Navigation

​Tools and Enforcement

​Branch Naming Check

​Best Practices

​Writing Good Commit Messages

​Coordinating Commits In Shared Checkouts

​Branch Management

​Synchronizing Release Branches

​Pull Request Workflow

​Conclusion

Overview

Conventional Commits

What are Conventional Commits?

Types

Scopes

Breaking Changes

Examples

Conventional Branches

What are Conventional Branches?

Branch Types

Naming Rules

Examples

Merge Commit Exception

How These Conventions Improve Our Workflow

1. Automated Changelog Generation

2. Semantic Versioning

3. Automated Release PRs And Package Publishing

4. Better Code Reviews

5. Simplifying Navigation

Tools and Enforcement

Branch Naming Check

Best Practices

Writing Good Commit Messages

Coordinating Commits In Shared Checkouts

Branch Management

Synchronizing Release Branches

Pull Request Workflow

Conclusion