Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
178 lines (128 loc) · 5.2 KB

CONTRIBUTING.md

File metadata and controls

178 lines (128 loc) · 5.2 KB

🧭 Contributing to MirageJS ORM

First off — thank you for taking the time to contribute!
This project is an open-source rework of MirageJS that focuses on its ORM capabilities, modern type system, and clean API.
Contributions, discussions, and feedback are very welcome ❤️

🪜 Table of contents

⚙️ Getting started

  1. Fork the repository and clone your fork:

    git clone https://github.com/<your-username>/orm.git
cd orm

  2. Install dependencies:

    pnpm install

  3. Run checks and tests:

    • Lint, format, and types: pnpm check:all
    • All tests (type tests + unit tests): pnpm test:all
    • Everything before a PR: pnpm build:checks

🧑‍💻 Development workflow

All work should be done on feature branches, not directly on main.

  1. Create a new branch:

    git checkout -b feat/add-new-feature // fix/issue-with-factory

  2. Make your changes and commit them following the Conventional Commits format (see below).

  3. Push your branch and open a Pull Request to main.

📝 Commit convention

This project follows the Conventional Commits specification.
Each commit message must have a clear, structured format:

<type>(<scope>): <short summary>

Scopes (required for features and fixes)

Scope Use for
lib Changes to the main library (lib/) — core ORM, schema, models, serializers, etc.
example Changes to the example project (examples/task-board/) — demo app, tests, docs.

Use these scopes so that changelogs and reviews can distinguish library changes from example-only changes.

Common types

Type Use for
feat New features
fix Bug fixes
docs Documentation only changes
style Code style (formatting, missing semicolons, etc.)
refactor Code changes that neither fix a bug nor add a feature
perf Performance improvements
test Adding or updating tests
chore Maintenance tasks (deps, configs, CI)

Examples

feat(lib): add factory builder support
fix(lib): correct relation key resolution in serializer
feat(example): add login help dialog
docs(example): update task-board README with schema setup
docs: update contribution guide with scope requirements

Notes

  • Scope is required for feat and fix: use feat(lib) or feat(example) (or fix(lib) / fix(example)).
  • Keep summaries short (under 80 chars).
  • Use present tense (“add” not “added”).
  • Avoid capitalizing the first word after the colon.
  • You can include a body or footer (e.g. to reference issues) if needed.

🔀 Pull requests

Before opening a PR:

  1. Make sure all build checks pass locally: 
    pnpm run build:checks
  2. Review your PR checklist in .github/PULL_REQUEST_TEMPLATE.md.
  3. Ensure commits follow Conventional Commits.
  4. Squash or rebase if your branch history is noisy.

Once merged, your commits will automatically be included in the changelog via the release process.

🧪 Testing

There are two test scripts; use test:all to run both:

  • pnpm test — Runs unit tests (Vitest).
  • pnpm test:types — Runs type tests (Vitest with --typecheck).
  • pnpm test:all — Runs type tests then unit tests (handy before pushing).

Other useful commands:

  • pnpm test:watch — Unit tests in watch mode.
  • pnpm test:coverage — Unit tests with coverage.

Run only a subset (by pattern):

pnpm test -- src/model

🎨 Code style

The repository uses ESLint and Prettier for code consistency, and TypeScript strict mode for type safety.

Check (CI-style, no edits):

  • pnpm check:lint — Lint lib/src.
  • pnpm check:format — Check Prettier formatting.
  • pnpm check:all — Lint + format + type-check (handy before committing).

Fix (auto-fix lint and format):

  • pnpm fix:lint — Auto-fix ESLint issues.
  • pnpm fix:format — Apply Prettier.
  • pnpm fix:all — Run both (handy before committing).

🚀 Releases

Releases are automated with Changesets and follow Semantic Versioning (semver).

To add a changelog entry for your PR:

pnpm changeset

This will guide you through writing a short description of the change and its version bump (patch, minor, or major).

❤️ Thank you

Your time and contributions help evolve the next generation of MirageJS ORM.
Every issue, PR, and idea helps us refine this library — thank you for being part of it!
⚡