Team Workflow and Governance

Developers integrate small changes frequently into a shared main branch, often using short-lived branches and strong automated checks.

What this module covers

Branch naming and commit conventions Conventional Commits and changelog generation Code review expectations Protected branches and required checks CODEOWNERS and review routing Merge queue concepts Release branches, tags, and backports

Repository permissions and least privilege Monorepo versus multirepo Migration and repository cleanup

Handling binary files and generated code

13.1 Common branching models

Developers integrate small changes frequently into a shared main branch, often using short-lived branches and strong automated checks.

Each feature or fix is developed on a separate branch and reviewed before integration.

A release branch stabilizes a version while ongoing work continues elsewhere. Fixes may need backporting.

Contributors work in forks and submit changes through a review process, useful for open-source projects and permission-separated collaboration.

No workflow is universally best. Select one that matches release cadence, risk, team size, review requirements, and deployment architecture.

13.2 Commit conventions

Conventional Commit-style examples:

If used, define how breaking changes and release versions are represented. Do not assume the commit prefix automatically triggers releases unless the tooling is configured to do so.

Checking messages automatically Output (CPython 3.13.1):

A check like this can run in a commit-msg hook for fast feedback, but — as Module 12 notes — hooks are bypassable, so the authoritative check belongs in CI or the hosting platform. The ! marks a breaking change in this convention.

feat: add firmware version command
fix: validate diagnostic payload length
docs: explain local build setup
test: cover timeout boundary
refactor: isolate CAN frame parsing
build: pin CMake toolchain version
ci: cache dependency downloads

import re

PATTERN = re.compile(r"^(feat|fix|docs|test|refactor|build|ci|chore|perf)(\([a-z0-9-]+\))?(!)?: [a-z].{0,70}$")

messages = [
    "feat: add firmware version command",
    "fix(can): validate diagnostic payload length",
    "build!: require CMake 3.25",
    "Fixed stuff",
    "feat: Add Uppercase Summary",
    "docs explain local build setup",
]
for m in messages:
    print(f"{'ok  ' if PATTERN.match(m) else 'FAIL'}  {m}")

ok    feat: add firmware version command
ok    fix(can): validate diagnostic payload length
ok    build!: require CMake 3.25
FAIL  Fixed stuff
FAIL  feat: Add Uppercase Summary
FAIL  docs explain local build setup

13.3 Branch protection and review

Common controls:

Require successful CI checks.

Require reviews for protected branches.

Restrict force pushes and deletion.

Require signed commits/tags where appropriate.

Apply CODEOWNERS or equivalent ownership rules.

Limit who can publish releases.

Keep administrator bypass rights limited and audited.

Exact controls depend on hosting platform and plan.

13.4 Monorepo versus multirepo

A monorepo can simplify coordinated changes and shared tooling but requires scalable build/test selection, ownership, and repository performance. Multirepo can support independent ownership and release cycles but increases cross-repository coordination and version synchronization work.

13.5 Generated code and binary policy

Decide whether generated source, firmware binaries, model files, test artifacts, and third-party code belong in the repository. Document generation commands and versions. Use release/artifact storage for large outputs when appropriate, and avoid committing transient build products unless there is a specific reason.

Quiz

? Which branching model integrates small changes into the main branch frequently, protected by strong automated checks?
+ Trunk-based development :: Short-lived branches, frequent integration.
- Release-branch workflow :: Stabilises a version on a separate branch.
- Fork-based workflow :: About repository ownership and permissions.
- GitFlow :: Uses long-lived develop and release branches.

? Why are local Git hooks not a security control?
+ A developer can skip or edit them. :: Enforce critical checks in CI and server-side rules.
- They run too slowly. :: Speed is not the issue.
- They cannot read commit messages. :: `commit-msg` hooks can.
- They only work on Linux. :: They work on all platforms.

? Which are common branch-protection controls? (select all that apply)
+ Required CI checks before merge :: Prevents untested merges.
+ Required reviews :: At least one approval.
+ Restricting force pushes and deletion :: Protects published history.
- Allowing everyone to bypass rules :: Bypass should be limited and audited.