Skip to main content

Commit message conventions

Serenity/JS Continuous Delivery Pipeline uses Conventional Commits standard and analyses the files you've modified to determine if the changes you propose require version bump and a release.

For example, changes to any files in the packages directory will result in a release of the new version of Serenity/JS to npmjs.com and the Serenity/JS website being updated, while changes to any files in the documentation will only result in the website being updated.

Additionally, if your changes are marked as feat or fix, they will be included in the changelog and release notes. For example:

  • docs(website): corrected a typo in the handbook will not be included in the changelog
  • feat(console-reporter): improved stats aggregation will be included in the changelog
Your commit messages matter

Please pay attention to what you write in your commit messages, as messages marked as feat and fix are included in the changelog and release notes.

Handling Pull Requests that trigger a release​

When you raise a Pull Request, the Serenity/JS pipeline will automatically calculate the version number based on the commit messages and the files you've modified, according to the following rules:

  • if your Pull Request contains a single commit with a fix message, e.g. fix(core): corrected a typo in the API docs, the pipeline will bump the patch version of the affected module, e.g. @serenity-js/core, and other Serenity/JS modules that rely on it and release them together to npmjs.com.
  • if your Pull Request contains a commit with a feat message, the pipeline will bump the minor version
  • if your Pull Request contains multiple commits, some of which are fix, some feat, some style, refactor or docs, the pipeline will determine the most significant change and bump the minor version if there's at least one feat commit, or the patch version if there are only fix commits.
Serenity/JS Continuous Delivery Pipeline

The Serenity/JS pipeline runs thousands of package- and integration-level tests across a number of supported Node.js runtimes, browsers, and operating systems to help make sure new changes don't introduce regressions and takes only about 15 minutes to complete 🚀

Squashing Pull Requests​

If your Pull Requests contains multiple commits affecting the same feature, it's fine to have the various commits follow the feat(scope): description and fix(scope): description format, as the pipeline will still calculate the version number based on the most significant change while including all feat and fix commits in the changelog and release notes.

However, if you don't want to have all your feat and fix commits to be added to the changelog and release notes, please let us know in the description of your Pull Request and make sure that the title of your Pull Request follows the commit message standard instead.

Commit message wizard​

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

If you get stuck at any point, please feel free to reach out on the Serenity/JS Community Chat and we'll help you out.

To use the commit message 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
> bin/commit.ts

cz-customizable standalone version
All lines except first will be wrapped after 100 characters.
? Select the TYPE of change you're proposing:
  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)

For example, if you wanted to make a documentation change to the Serenity/JS website to explain the importance of commit messages, you'd select: docs as the type of change, and website as the scope of the change:

All lines except first will be wrapped after 100 characters.
? Select the TYPE of change you're proposing: docs
? Denote the SCOPE of this change: website

? WHAT did you change? Please write a SHORT, IMPERATIVE tense description of the change:

 explained the importance of commit messages

? WHY did you change it? Provide a LONGER description of the motivation behind the change (optional).
  Use "|" to break new line

 This should help developers follow the commit message format conventions |
 and make contributing to Serenity/JS easier

? List any GitHub TICKETS affected by this change (optional). E.g.: #31, #34:
 closes #2263

###--------------------------------------------------------###
docs(website): explained the importance of commit messages

This should help developers follow the commit message format conventions
and make contributing to Serenity/JS easier

Related tickets: closes #2263
###--------------------------------------------------------###

? Are you sure you want to proceed with the commit above? (Yneh)

Referencing and closing GitHub tickets

If your change is related to a specific GitHub ticket, please mention it in your commit message when the wizard asks about it, e.g. #2263.

If your change should close the related ticket altogether, please use the closes #<ticket number> syntax, e.g. closes #2263.

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