Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
112 lines (78 loc) · 3.51 KB

CONTRIBUTING.md

File metadata and controls

112 lines (78 loc) · 3.51 KB

Contributing to MAXSIM

Thank you for your interest in contributing! This guide covers everything you need to get started.

Development Setup

# 1. Fork https://github.com/maystudios/maxsimcli, then clone your fork
git clone https://github.com/<your-username>/maxsimcli.git
cd maxsimcli

# 2. Install dependencies
npm install

# 3. Build all packages
npm run build

# 4. Run unit tests
npm test

# 5. Run e2e tests (requires build)
cd packages/cli && npx vitest run --config vitest.e2e.config.ts
# Or simply: `npm run e2e`

Note: E2E tests are not yet implemented. The command will be skipped if no test files are found.

Requirements: Node >= 22.0.0

Branch Naming

Use descriptive, lowercase, hyphen-separated names:

feat/add-new-command-name
fix/install-path-resolution
docs/update-contributing-guide
refactor/cli-router-cleanup

Commit Messages — Conventional Commits

All commits must follow Conventional Commits. This is not optional — semantic-release reads commit prefixes to determine version bumps and changelog entries automatically.

Format

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

[optional body]

Allowed Types

Type When to use Version bump
fix: Bug fix patch (1.0.8 → 1.0.9)
feat: New feature minor (1.0.8 → 1.1.0)
fix!: / feat!: Breaking change major (1.0.8 → 2.0.0)
chore: Maintenance, build changes, version bumps none
docs: Documentation only none
test: Adding or fixing tests none
refactor: Code change that's neither fix nor feature none

Examples

git commit -m "fix(install): copy maxsim-tools.cjs to bin/ during install"
git commit -m "feat(cli): add new phase:insert command"
git commit -m "docs: update README with new model profiles"
git commit -m "feat!: rename STATE.md fields — breaks existing projects"

Note: chore:, docs:, and test: commits do not trigger a publish to npm. fix: and feat: do.

Code Style

This project uses Biome for linting.

npm run lint             # Check
npm run lint -- --write  # Auto-fix (passes --write through to Biome)

Biome runs automatically on CI. PRs with lint failures will not be merged.

Project Structure

Key locations for common tasks:

Task Location
Add a new CLI tool command packages/cli/src/cli.ts (registry-based dispatch — currently a stub; commands will be registered in a future phase) + relevant module in src/core/
Add a new workflow templates/workflows/
Add a new agent templates/agents/
Change model assignments MODEL_PROFILES in packages/cli/src/core/types.ts
Change install behavior packages/cli/src/install/index.ts
Modify hooks packages/cli/src/hooks/

Static assets (commands, agents, workflows) live in templates/ at the repo root. See PROJECT.md for the full architecture overview.

Before Submitting a PR

  • npm run build passes with no errors
  • npm test passes
  • npm run lint passes
  • Commits follow Conventional Commits format
  • No direct edits to packages/cli/README.md — it is auto-generated by the build from the root README.md

Bug Reports & Feature Requests

Use the GitHub issue templates — they guide you through providing the information needed to act on your report quickly.