Skip to main content

Proposing enhancements

Serenity/JS is an open-source project and is open to your contributions and Pull Requests.

Before putting your time and effort into a pull request, though, please gauge the potential interest in incorporating your idea either by raising a ticket on Serenity/JS GitHub or chatting with the development team on the Serenity/JS Community Chat on Gitter.

Serenity/JS Contributors Chat

Working with the Serenity/JS codebase​

If you have decided to work on a pull request, you'll need to:

  • Fork the Serenity/JS mono-repo to your GitHub account
  • Create a new branch in your forked repository
  • Click on the Contribute with Gitpod badge in the readme of your forked repository to provision your free Gitpod workspace.
  • When you're done, run the full local build make clean verify report
  • Commit your changes following the conventional commits standard, push them to your forked repository, and raise a pull request - more on commit message standard and automated releases below.
Did you know?

Clicking on the Gitpod badge in the readme on your branch in your forked repository will provision a new Gitpod workspace. The workspace is created with all the dependencies necessary to successfully build and test Serenity/JS, including the operating system-level dependencies, web browsers, Node.js, and node modules.

This virtual workspace is free of charge thanks to the generous free tier offered by Gitpod to open-source projects, and typically gets provisioned in seconds thanks to the effort Serenity/JS maintainers have put into optimising it for you 😊

Alternatively, if you prefer to work on the pull request on your own machine instead of using Gitpod, you'll need to:

  • Clone your fork to your machine
  • Make sure you have the runtime dependencies installed
  • Install the Node.js dependencies by running make install in the project root. Serenity/JS uses Lerna.js to manage the @serenity-js/* modules you'll find in the mono-repo, so it will take care of propagating the npm ci and other commands to the modules (this step happens automatically in the Gitpod workspace)
  • Make sure you can build the Serenity/JS project on your machine and all the unit- and integration tests are passing before introducing any changes by running make clean test to run the package-scope tests or make clean verify to run package-scope and integration tests.
  • Introduce the changes you wish to propose and update or introduce any package-scope and integration tests that are relevant.
  • Run full local build before committing - make clean verify report
  • Commit your changes following the Serenity/JS conventional commits standard, push them to your forked repository, and raise a pull request - more on commit message standard and automated releases below.

Serenity/JS mono-repo structure​

Serenity/JS mono-repo contains the following main directories:

  • packages - this is where all the Serenity/JS modules and their associated unit and package-scope tests live
  • integration - this is the home of the integration tests that exercise the Serenity/JS modules once they're transpiled from TypeScript to JavaScript
  • examples - when the changes you want to introduce pass their unit tests and integration tests, you can use the mini-projects located here for exploratory testing and experimentation. Those example projects simulate the framework's target execution environment, so you can use them to look at your changes from the perspective of the people who'll be using them soon!
  • documentation - Serenity/JS website

Building and testing Serenity/JS​

Serenity/JS Makefile drives the entire build process.

Here's a list of commands you'll need to build and test Serenity/JS locally:

  • make - same as running make install clean compile,
  • make install - installs dependencies across the Serenity/JS monorepo,
  • make cc - removes Nx.js build cache
  • make clean - removes any artifacts produced while running the tests,
  • make test - executes the unit tests located under packages/*/spec
  • make integration-test - executes the integration tests located under integration/*/spec,
  • make verify - runs ESLint, transpiles TypeScript to JavaScript, runs the unit tests and other package-scope tests, runs the integration tests located under integration/*/
  • make verify report site - same as verify, but additionally generates aggregated test and coverage reports and produces the serenity-js.org website. This is the full local build you should run at least once before committing your changes and submitting the pull request.

If you encounter any issues, let us know on the Serenity/JS Community Chat. And don't be shy, we're here to help 😊