Developers

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
• Requesting Features
• Opening a Pull Request
• Code Style
• Testing
• Releasing/Versioning

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:

• Check if the bug has already been reported

  You can do this by searching the repository. This gives us more time to focus on existing bugs, and it might help you find a solution more quickly.

• Make sure your software is up to date

  It may be that your bug has already been fixed in a newer version.

• Provide steps to reproduce

  Your bug will generally get fixed much more quickly if you provide clear steps to reproduce the problem. This should include the version numbers of any relevant software. If you don’t provide this, then it’ll almost certainly be our first question

• Write a failing test

  This is not required to file a bug report, but we’ll love you if you add one! Writing a failing unit or integration test and opening a pull request will help us quickly locate the issue.

• Open multiple bug reports

  If you have multiple different bugs, it’s best to open each as a separate GitHub issue.

Requesting features

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

• Check if the feature has already been requested

  You can do this by searching the repository. You may find that somebody has already asked for the feature you’re thinking of! If this is the case then feel free to join in the comments.

• Phrase as user needs

  If you phrase your feature request as a user need rather than a proposed solution, it opens up more potential for discussion and collaboration – way more fun for everyone.

• Open multiple feature requests

  If you have multiple different requests, it’s best to open each as a separate GitHub issue.

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:

• Discuss features first

  If you’re thinking of opening a pull request that adds a feature, you’ll save yourself some time and effort if you discuss it in a feature request first. The review is guaranteed to go more smoothly if we’ve chatted about it beforehand.

• Write and run the tests

  Each project should have instructions on how to run the tests. If you haven’t done much automated testing before then get in touch and we’ll teach you a bit! New features should have new unit or integration tests, and bugs should have tests to prevent regressions.

• Update the documentation

  The user documentation should be kept up to date with any changes made. Use inline code comments as developer documentation, focusing more on why your code does something than what it’s doing.

• Follow the code style

  We have a code style, and the pull request build will fail if this isn’t followed. If the code style varies for a project already then it’s best to follow the example set in that project. We’re not mean, we just like consistency a lot

• Reference other issues

  When fixing a bug, reference the original report; when adding a feature, link to the original feature request. It’ll help us massively!

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

• Tabs for indentation (except in package.json and Markdown files)
• 100 characters per line
• Don’t abbreviate names (request is better than req)

JavaScript style

• Use semicolons
• Use ', not "
• Use strict mode 'use strict';
• Use ES6 where available
• Commas at the end of the line, not the start

HTML style

• Use HTML5
• Use lowercase names for tags/attributes
• Use " to quote attributes

CSS/Sass style

• Use BEM-style naming for classes
• One selector per line
• One property/value per line
• Don’t style IDs

Markdown style

• Add two empty lines above a h2 (to break up sections)
• Indent lists and quotes (by two spaces)
• Use reference-style links as much as possible

Testing

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

• Mocha for unit and integration testing (with Proclaim as an assertion library)
• JSHint, JSCS, and EditorConfig for code quality and consistency
• Make as a build tool

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.

Releasing/Versioning

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

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