Contributing to Serenity/JS

Hello and thank you for deciding to contribute to help Serenity/JS move forward!

You're awesome and we greatly appreciate your time and talent 😊

Serenity/JS is a safe space where everyone is welcome to contribute, so feel free to ask questions and discuss the ideas you have on the Serenity/JS Community Chat and we'll do our best to help you get started.

If anything in the Serenity/JS documentation is not as clear as it could be or you have ideas on how to improve the codebase to make the life of our community easier - please let us know! Your feedback will help us make Serenity/JS better for everyone.

If you experience any issues trying to make your contribution, please raise a ticket on Serenity/JS GitHub. Your developer experience is really important to us, so we treat any issues here with the same seriousness we treat defects in code 🐛

Find your way to contribute​

Serenity/JS offers a variety of ways to contribute. If you'd like help finding a way that works for you, join the Serenity/JS Community Chat and reach out to the maintainers there.

The most popular ways to contribute include:

• helping us spread a good word about Serenity/JS, for example by tweeting about your experience, or simply giving it a ⭐ on GitHub
• giving the Serenity/JS tickets you care about a 👍
• improving documentation
• helping maintainers on the Serenity/JS Community Chat
• creating educational content - blog posts, tutorials, videos are all welcome!
• reporting any bugs you encounter while using Serenity/JS
• raising feature requests describing what Serenity/JS should also help you do
• contributing code
• sponsoring our work via the GitHub Sponsors programme

If you're new to open source and would like to get up to speed with the basic concepts, check out this excellent guide on "How to make your first open source contribution" by Ceora Ford.

Join the GitHub Sponsors programme!​

Delivering new features, writing documentation, answering your questions on GitHub, StackOverflow and Gitter, and making sure that Serenity/JS is up-to-date with all the security patches and bug fixes take a lot of time.

We're talking about an average of 40-100 hours per maintainer per month on top of our day jobs, for which none of us are getting paid.

We're using the GitHub Sponsors program to help raise funds and secure development time to make Serenity/JS better for everyone! 🚀

If you feel that Serenity/JS has helped you save at least a couple of dollars worth of your time, please support our work by joining the Serenity/JS GitHub Sponsors programme!

Help to improve the docs​

Serenity-js.org website is made of two main components:

• Serenity/JS Handbook with articles and tutorials helping you to get started with the framework
• Serenity/JS API Documentation describing the public APIs available to developers using Serenity/JS to build their tests and test automation systems.

Serenity/JS Handbook​

The Serenity/JS Handbook is an evolving project and there are parts of the book that you might find incomplete, or simply not written yet.

You can contribute to the evolution of the Serenity/JS Handbook by:

• correcting any errors you find - via Edit this page link at the bottom of each page and raising a Pull Request
• sharing your ideas for topics you'd like to see covered - via GitHub issues
• sponsoring the Serenity/JS project via the GitHub Sponsors Programme, so that the maintainers can secure more time to write and improve the documentation for you

Serenity/JS API Docs​

The Serenity/JS API Documentation is generated automatically based on the TSDoc comments in the codebase. If you spot an issue in the API docs or want to add a new example, click on the code icon next to the name of the class or method of interest, just like this one here.

The code icon will take you straight to the TSDoc used to generate a given description or example, which you can fix via Pull Request the same way you'd fix the code.

Proposing changes to the website​

The Serenity/JS website is located under documentation in the Serenity/JS mono-repo.

The website is built with Docusaurus and uses the Docusaurus Plugin TypeDoc API to produce the API docs.

To start the local development server, run:

make install
cd documentation/serenity-js.org
npm start

To test the build process, run:

make install
make site

Report an issue​

If you believe you have found a bug in Serenity/JS please raise a ticket on Serenity/JS GitHub.

When reporting a bug, please kindly remember that the easier you make it for the maintainers to "see what you see", the sooner your ticket will be looked at:

• Give the ticket a succinct yet descriptive title - compare "Feature X is broken" vs, "Feature X is not triggered upon event Y"
• Mention the environment where you spotted the bug. What was the browser and operating system? What versions of runtime dependencies did you use?
• Provide a detailed description of what happened and don’t leave any important facts out. That said, try not to include any extraneous details that could derail or distract the people trying to help reproduce the issue you found.
• Explain how the behaviour you observed is different from what you believe should have happened instead
• Provide supplementary information:
  • If you can reproduce and isolate the issue, use one of the Serenity/JS Project Templates to create a minimalistic example that demonstrates the problem and attach a link to it to your ticket. While this requires a bit more work on your side, it will help us sort out the problem much quicker.
  • If you can reproduce the issue, but can't isolate it, add the StreamReporter to your Serenity/JS stage crew, run the test again to trigger the bug, and attach the StreamReporter's log to your ticket
  • If you can't reproduce the issue, please attach any additional information that might help us figure out what happened - screenshots and test execution logs are particularly useful.

Propose an enhancement​

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.

Working with the Serenity/JS code base​

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 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.

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 conventional commits standard, push them to your forked repository, and raise a pull request - more on commit message standard and automated releases below.

Conventional commits and automated releases​

Serenity/JS uses Conventional Commits standard to identify if the changes you propose require a release.

To make it easy for you, we've added a little wizard that will help you generate a commit message compliant with the standard, and configured a pre-commit git hooks and a CI/CD pipeline-level check to ensure everything's correct.

To use the wizard, add the files you changed to git index using git add <filename> or your favourite IDE like VSCode or JetBrains

Next, invoke the following command in the root directory of your cloned Serenity/JS project:

npm run commit

Which should yield output similar to the below:

npm run commit

> serenity-js-monorepo@3.0.0-monorepo commit
> ./node_modules/cz-customizable/standalone.js

cz-customizable standalone version
All lines except first will be wrapped after 100 characters.
? Select the TYPE of change you're proposing: (Use arrow keys)
❯ feat:     A new feature that will be available to the developers using Serenity/JS, e.g. a new public API
  fix:      A bug fix, prepared typically to address a specific GitHub ticket
  docs:     Documentation only changes affecting the website, examples, or the API docs
  style:    Changes that do not affect the meaning of the code, e.g. formatting, fixing missing semicolons, etc.
  refactor: Improvements to code that do not affect the observable behaviour of Serenity/JS
  perf:     A code change aimed at improving performance
  test:     Improvements to existing internal tests, or adding missing tests
(Move up and down to reveal more choices)

Once you're happy with the commit message, push your commit to your forked repository, and raise a pull request.

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 😊

Enjoy Serenity!

Jan Molak and the Serenity/JS team