Proposing enhancements

Serenity/JS welcomes ideas and contributions of all sizes. Before starting any work, check whether your enhancement aligns with community needs:

• Open an issue on the Serenity/JS GitHub repository
• Chat with the team on the Serenity/JS Community Chat on Gitter

Both options help confirm interest and reduce the chance of duplicate or unnecessary work.

Working with the Serenity/JS codebase

Once you’re ready to propose a change, follow this workflow.

Prepare your working environment

Option A: Use GitHub Codespaces (recommended)

• Fork the Serenity/JS mono-repo
• Create a new branch in your fork
• Create a GitHub Codespace in your fork: Code → Create Codespace on main
• After implementing your changes, run the full build:

make clean verify report

Option B: Develop locally

• Fork the Serenity/JS mono-repo
• Create a new branch in your fork
• Clone your fork to your machine
• Install the runtime dependencies: Node.js LTS and Java Runtime Environment
• Install the Node.js dependencies - Serenity/JS uses Lerna.js, PnPm and Node.js Corepack

make install

• Verify your environment is set up correctly and all tests are passing:

make clean test

Implement your changes

• Implement your change and update/add tests
• Run a full local build before submitting:

make clean verify report

Submit your changes

• Follow the conventional commits standard when writing commit messages
• Push your branch to your fork
• Open a pull request
• If automated checks fail, update your branch and rebuild until everything passes

Understanding the Serenity/JS codebase

The Serenity/JS mono-repo includes three main areas:

• packages/ - Source for all Serenity/JS modules, along with unit and package-level tests
• integration/ - Integration tests that run against transpiled JavaScript artifacts
• examples/ - Small sample projects that let you experiment with your changes in a realistic environment

Documentation for the Serenity/JS website lives in a separate repository: serenity-js/serenity-js.org For documentation-focused contributions, see the Improving Documentation guide.

Building and testing Serenity/JS

The build process is driven by the main Makefile. Common commands:

• make - runs install, clean, compile
• make install - installs all mono-repo dependencies
• make cc - clears Nx.js build cache
• make clean - removes build artifacts
• make test - runs unit tests in packages/*/spec
• make integration-test - runs integration tests in integration/*/spec,
• make verify - runs linting, transpilation, unit tests, and integration tests
• make verify report - full build, generating aggregated test and coverage reports (Run this at least once before submitting a pull request)

If you run into issues, connect with the team via the Serenity/JS Community Chat. And don't be shy, we're here to help 😊