Skip to main content
This page covers everything you need to know about contributing to MDCMS, from branch naming to code conventions and the PR process.

​
Development Workflow

1

Create a feature branch

Always branch off main before making changes:
2

Develop with tests

Write failing tests first, then implement until they pass. Run unit tests during development for fast feedback:
3

Verify everything passes

Before committing, run the full CI gate:
This runs format check, typecheck, unit tests, and integration tests sequentially.
4

Commit with conventional commits

​
Branch Naming

All branches follow a type/kebab-case-description pattern: Examples: feat/media-upload-drag-drop, fix/reference-resolution-null, chore/bump-elysia.

​
Commit Conventions

Commits follow the conventional commits format:
The scope is the package name or area of the codebase (e.g., server, studio, cli, shared, sdk, modules). Rules:
  • First line only — no body, no footer
  • Keep the message concise and descriptive
  • Use imperative mood (“add feature” not “added feature”)

​
Code Conventions

​
TypeScript

  • Strict mode is enabled across all packages
  • Prefer type inference when types are obvious from context
  • Use explicit types for function parameters and return values at module boundaries

​
Formatting

Prettier handles all formatting. Run it before committing:

​
Naming

  • No abbreviations except widely known ones (id, url, ctx)
  • Self-documenting names — comments explain “why”, not “what”

​
General Principles

  • DRY — Extract repeated values to constants, repeated logic to functions
  • No unrelated changes — Keep PRs focused on a single concern
  • No debug artifacts — Never commit console.log, debugger statements, or test artifacts

​
PR Process

1

Create a pull request

Push your branch and open a PR against main:
2

CI runs automatically

GitHub Actions runs the full CI pipeline on every PR. All required checks must pass before merge.
3

Address review feedback

Make changes in new commits (do not force-push during review). Keep the conversation going until the reviewer approves.
4

Merge

Once approved and CI passes, the PR is merged into main.

​
Pre-push Gate

A git pre-push hook is installed automatically when you run bun install. It executes:
This runs the following checks sequentially:
  1. Format check — Verifies code matches Prettier formatting
  2. Typecheck — Runs TypeScript compiler across all packages
  3. Unit tests — Runs all unit tests
  4. Integration tests — Runs integration tests (requires Docker services running)
The pre-push hook blocks the push if any check fails. Fix all failures before pushing. Do not skip the hook with --no-verify unless you have a specific reason.
Run bun run quality (format + typecheck) as a quick sanity check during development. Save the full bun run ci:required for when you are ready to push.