So you’d like to contribute some code, report a bug, or request a feature? You’re in the right place! This guide covers a lot of the basics of starting to contribute back to Pa11y.

Reporting bugs

We like it when people report bugs in our projects, and would definitely rather know about them than be left in the dark. We use GitHub Issues for bug tracking. When filing a bug report, there are some guidelines you can follow which will help us quickly resolve your issue:

Requesting features

When making a feature request, it’s helpful for us if you follow these guidelines.

It’s important to note that we can’t accept every feature request, we’ll always discuss why if we’re not going to accept them though.

Opening a pull request

Please do! All of the code in Pa11y projects is peer-reviewed, this isn’t as scary as it sounds, we’re a considerate bunch and we love to help people learn. There are some things you can do to help this review go smoothly:

Code style

Pa11y has a code style, but we’ll keep it brief. The best way to ensure you stick to it is to make your work consistent with the code around it. We also have ways to enforce the code style, so don’t let it get in the way of your flow – you can fix it afterwards!

General style

JavaScript style

HTML style

CSS/Sass style

Markdown style


Pa11y projects should always be well tested and consider code quality/consistency. Pa11y projects normally use the following tools for this:

Unit testing

As much code as possible should be unit tested with Mocha, and a coverage of 90 or higher should be verified with nyc. Sinon and Mockery are normally used for mocking.

If in doubt, speak to a member of the team – someone will be happy to help. Also the existing projects make good use of these tools, so looking through the tests might help.

Integration testing

We also use Mocha for integration tests. These are normally only added for larger projects with more complex integrations. For example an extensive command-line tool or a database-driven website.

Code quality and consistency

For JavaScript code quality, you should use the Pa11y Lint Config module. This gives each project an updatable shared code style.

Build tools

Ideally every project should implement at least the following Make targets:

make install  # Install dependencies (`make deps` also acceptable in legacy projects)
make test     # Run all of the tests (unit, integration, coverage)
make verify   # Run linters (`make lint` also acceptable in legacy projects)
make ci       # Alias to `make verify test`

Most projects now use a shared Makefile for this, which will provide all of the required targets.


This section is for core contributors who have write access to repositories. Hi core contributors :wave:

All of our projects are versioned using Semantic Versioning (except for this site), you should familiarise yourself with this. The following guide will outline how to tag and release a new version of all projects, it assumes that all the code you wish to release is now on the master or main branch.

  1. Review the commits since the last release. You can find the last release in the git log, or by using the compare feature on GitHub. Make sure you’ve pulled all of the latest changes.

  2. Decide on a version. Work out whether this release is major, minor, or patch level. Major releases are generally planned out; if a breaking change has snuck into master without prior-planning it may be worth removing it or attempting to make it backwards-compatible.

  3. Write the changelog. Most projects have a file in the root. You should create a new section at the top with the new version number and the date, then outline all of the changes as a list. Follow the style of the rest of the document.

  4. Update any package files. Add the new version to package files. This could include package.json or bower.json as examples. A quick way to check if you’ve got them all is by running: git grep "current-version-number"

  5. [legacy] Update the README. Some legacy projects include the version number in the README file. This should be updated to reflect the new version.

  6. Commit your changes. Commit the changes to changelong, README, and package files. The commit message should be “Version x.x.x” (exact casing, and with no “v” preceeding the version number). This is the only time you’re allowed to commit directly to master.

  7. Add a tag. Tag the last commit with the new version number using git tag x.x.x (note there’s no “v” preceeding the version number).

  8. Push your commit and tag. You can push your version commit and tag now. It’s really important to push the tag as well! Run: git push && git push --tags

  9. Publish. If the project is on npm then you’ll need to have access, and run npm publish.

  10. Announce. You should announce that a new release has been made on the Pa11y news page. Follow the style of previous announcements, but feel free to give it some personality!

  11. Celebrate. :tada::beer::cake::cocktail: