Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
136 lines (98 loc) · 4.15 KB

CONTRIBUTING.md

File metadata and controls

136 lines (98 loc) · 4.15 KB
Raw

Contributing to Cordis

Thanks for your interest in contributing! This document covers how to get started with development, and what is expected when you open a pull request.

Repository overview

Cordis is a TypeScript monorepo managed with Yarn 4 workspaces and yakumo. It contains the following packages under packages/:

  • core — the framework runtime
  • create — scaffolding for new projects
  • group — group model utilities
  • hmr — hot module reloading support
  • include — config file inclusion
  • loader — plugin loading
  • logger-console — console log formatting
  • timer — timer model utilities
  • utils — shared utilities

There are also external workspaces under external/.

Prerequisites

  • Node.js 24 or newer (CI runs on Node 24 and 26)
  • Corepack enabled, so that the pinned Yarn version in package.json is used automatically
  • Git

Setting up the development environment

  1. Fork the repository on GitHub, then clone your fork:

    git clone git@github.com:<your-username>/cordis.git
cd cordis
git remote add upstream git@github.com:cordiverse/cordis.git

  2. Install dependencies:

    corepack enable
yarn

Common commands

Run everything from the repository root:

Command Description
yarn lint Lint the codebase with ESLint
yarn build Build all packages (esbuild, then type check with tsc)
yarn test Run the test suite with Vitest
yarn test:text Run tests with a text coverage report
yarn test:html Run tests with an HTML coverage report

To run commands for a single package, prefix the command with yarn yakumo and append the workspace name, for example:

yarn yakumo vitest --import tsx core

Making changes

  1. Base your work on the latest main:

    git fetch upstream
git checkout -b <branch-name> upstream/main

  2. Make your changes. Keep them focused: one logical change per pull request.

  3. Add tests for any behavior change. Tests live in packages/<package>/tests/ and are written with Vitest.

  4. Run the checks locally before pushing:

    yarn lint
yarn build
yarn test

  5. Commit your changes and push to your fork:

    git push -u origin <branch-name>

  6. Open a pull request against cordiverse/cordis:main. If your change addresses an issue, reference it in the PR description (e.g. "Closes #123").

Commit message conventions

Commit messages follow Conventional Commits:

  • Use a type prefix: feat, fix, perf, refactor, chore, docs, test, etc.
  • Scope the message to the package you changed, e.g. fix(core): ..., feat(loader): ..., chore: ... for repository-wide changes.
  • Keep the subject line under 72 characters, starting with a lowercase letter.

Examples from the repository history:

fix(core): track direct service callers
feat(loader): use internal loader without `--expose-internals`
perf(core): avoid binding callbacks in event dispatch
chore: bump versions

Code style

  • The project uses the @cordisjs/eslint-config preset; run yarn lint before pushing.
  • TypeScript is compiled in strict mode; type errors fail the CI build.
  • Do not introduce new runtime dependencies without discussing them first.

CI

The build workflow runs three jobs on every pull request:

  • lint — ESLint
  • build — esbuild bundling and tsc type checking
  • test — the full Vitest suite on Node 24 and 26

All of them must pass before a pull request can be merged. You can reproduce them locally with yarn lint, yarn build, and yarn test.

Questions

If you are not sure whether a change is wanted, open an issue first to discuss it. The issue tracker is also the right place to report bugs and request features.