Contributing

Reporting Issues

A good bug report helps us fix the problem quickly without chasing you for more information. Before opening an issue, please:

Confirm you are on the latest version of the affected package.
Reproduce the issue with a minimal filter string and note whether you can reproduce it consistently.
Collect environment details: OS and version, Node.js version, package versions.
Check existing issues at github.com/prior-art/odata-filter/issues to avoid duplicates.

Once you are ready, open a new issue and include:

A clear title describing the problem.
The filter expression that triggers the issue.
The expected result and the actual result (including full error messages and stack traces).
Your environment details (OS, Node.js version, package version).
Steps to reproduce reliably.

Setup and Installation

To set up the project locally for development, follow the Installation Guide.

Clone the repository and install dependencies:

git clone git@github.com:prior-art/odata-filter.git
cd odata-filter
npm i

Build

npm run build
# or with just
just build

Test

npm test
# or with just
just test

Lint

npm run lint
# or with just
just lint

Code Contributions

Create a branch from main using the pattern <type>/issues-<number> (e.g. feat/issues-42).
Keep your branch up to date with main by rebasing.
Make your changes with focused, incremental commits following Conventional Commits format: <type>: [Issues: <number>] <description> (e.g. feat: [Issues: 42] add support for the has operator).
Ensure all tests pass and mutation coverage remains at 100%:
```
just test
just test-mutation
```
Open a pull request against main.
The CI pipeline runs automatically — resolve any failures before requesting review.
Address review feedback. Once approved, the PR is squash-merged into main.

Release Process

After merging, create a pre-release using the tag format {package}@x.x.x-rc.x (e.g. core@1.0.0-rc.1).
The pre-release publishes the package to GitHub Packages for testing.
Once the pre-release is validated, promote it to a full release using the tag format {package}@x.x.x (e.g. core@1.0.0).

Code Review Process

All pull requests undergo code review. Reviewers provide constructive feedback promptly. Please be responsive to comments and open to changes. Once approved, the PR is merged.

Communication

Open a GitHub Discussion for questions that are not bugs or feature requests.