CONTRIBUTING.md

March 14, 2026 ยท View on GitHub

Contributing Issues

Bug Reports

Please provide a (simple) way to reproduce the problem. A bug that can not be reproduced is less likely to be solved.

Feature Requests

Please also include the reasoning for the desired feature and not just its description. Sometimes it is obvious, but other times a few sample use cases or an explanation can come in handy.

Contributing Code

There are two types of code contributions.

Contributing Sample Grammars and Examples

This is probably the easiest way to contribute as it does not require any knowledge of chevrotain's internals. And each contribution is self-contained and limited in scope.

Sample Grammars contributions are particularly encouraged.

See some existing examples to get started.

Details:

  • An Example must include some tests with a _spec.js suffix.

Contributing To Chevrotain's Runtime Source code.

This can be more complex as more in-depth knowledge of Chevrotain internals may be needed.

Details:

  • ~100% test coverage is required.
    • It is possible to disable coverage for specific code, but there must be a very good reason to do so.

Development Environment

Chevrotain is developed as a mono-repo with a single (temporary state) productive package and multiple example packages.

Chevrotain uses npm tasks for the development flows. and bun + lerna for the monorepo management.

Initial Setup

In the root of this Repo:

  • bun install

Some basic dev flows to get started

Chevrotain is written using Typescript, so compilation to JavaScript is needed.

  • bun compile

Alternatively during development one would want to recompile on file changes.

  • bun compile:watch

The compilation result will appear in the lib folder in each sub-package.

Code Formatting

Chevrotain uses prettier to avoid caring about code formatting... To format your new code use:

bun format:fix

Running the central CI flow locally.

This is just another npm task which performs the whole flow including linting / doc generation / d.ts API creation / ...

  • bun ci

Committing Changes

This project enforces consistent commit message format same as in the Angular project.

it is recommended to use git cz CLI tool to create these conventional commit messages.

Release Process

The release process requires push permissions to master.

  • Update the CHANGELOG.
    • The header must be ## X.Y.Z (INSERT_DATE_HERE) (literally).
  • Update the BREAKING_CHANGES.md.
    • Only for major versions...
  • Push the changes related updates to master.
  • execute bun release:version and follow the instructions.
    • This will update version related files and push a new version tag to Github.
    • Github Actions will execute a deployment to npmjs.com due to this new tag.
    • Additionally, new website contents will be pushed to the gh-pages branch.
  • Check that the release was successful.

All Contributors must sign the CLA. The process is completely automated using https://cla-assistant.io/ simply follow the instructions in the pull request.