Contributing to RoleCraft

Thanks for your interest in contributing! Here's how you can help.

Quick Start

git clone https://github.com/rolecraft-sh/rolecraft.git
cd rolecraft
npm install              # also installs the pre-commit hook automatically
npm link                 # now `rolecraft` runs from your local checkout
npm test                 # 1000+ tests should pass

Requirements: Node.js >= 20. Dev dependencies (Biome, VitePress) install locally but never ship to users — the runtime stays zero-dependency.

Git Hooks

A pre-commit hook runs npm run lint before every commit and rejects the commit on lint errors. It is set up automatically by npm install via the postinstall script — no manual setup-hooks step is required.

To reinstall or repair the hook manually:

npm run setup-hooks

To bypass the hook once (e.g. for a work-in-progress commit), use git commit --no-verify — but CI will still fail the PR if lint errors remain.

Find Something to Work On

Start with issues labeled good first issue — they are small, self-contained, and perfect for new contributors.

Don't see anything you like? Open a feature request or ask in Discussions.

Make Changes

• Keep changes focused on a single concern
• Follow existing code style (no semicolons, ES modules, zero-dependency runtime)
• Business logic goes in src/api/, CLI output goes in src/commands/
• Add or update tests for any new functionality
• Run npm run lint and npm test before submitting — both must pass
• To auto-fix formatting and unused imports, run npm run lint:fix

Error Handling

Use UserError (from src/utils/errors.js) for user-facing errors. It automatically provides helpful suggestions alongside the error message:

import { UserError } from '../utils/errors.js'

// Instead of:
//   throw new Error('Failed to fetch npm package')

// Do:
//   throw new UserError('Could not fetch npm package "foo"', {
//     suggestion: 'Check the package name and your internet connection.',
//     detail: error.message, // shown with --verbose
//     code: 'NPM_FETCH_FAILED',
//   })

Field	Required	Shown	Purpose
message	yes	always	What went wrong, user-friendly
suggestion	no	always	What the user should do next
detail	no	--verbose	Technical details for debugging
code	no	--verbose	Machine-readable error code

Reserve plain throw new Error(...) for programming errors (bugs, invariants) that should never reach the user. All user-facing error paths should use UserError.

Tip: When adding a new command, always use UserError for argument validation errors (missing slug, invalid source, etc.).

Commit

Use conventional commits:

feat: add new feature
fix: correct bug in parser
docs: update installation guide
chore: bump dependencies

Open a Pull Request

1. Push your branch and open a PR against main
2. Write a clear title and description explaining what and why
3. Link any related issues
4. Wait for CI checks to pass (Tests + CodeQL)
5. The repository owner will review and merge

Need Help?

• Open a Discussion
• Check the docs site

Code of Conduct

Be respectful and constructive. Keep discussions focused on the code.

What Contributors Say

yukidev630	Contributing was straightforward, and it was easy to understand where to make the change. I had a great experience contributing to RoleCraft.
BenjaminAyivoh1	Contributing to RoleCraft was a great experience, especially as one of my first open-source contributions. The issue was clearly defined, and the maintainers were responsive throughout the process, which made it easy to understand the project and contribute confidently
linhaixin45-cmyk	Contributing to RoleCraft was straightforward because the issue clearly explained the problem, expected behavior, and relevant code paths, and the test suite made the fix easy to verify. The maintainer's quick, thoughtful review also made the experience welcoming.

---

Show Your Support

If rolecraft makes your workflow easier, consider starring the repo. It helps others discover the project.