Style Guide

Pull requests Hyperlink to this header

So you want to contribute code to BookWyrm: that rules! If there's an open issue that you'd like to fix, it's helpful to comment on the issue so work doesn't get duplicated. Try to keep the scope of pull requests small and focused on a single topic. That way it's easier to review, and if one part needs changes, it won't hold up the other parts.

If you aren't sure how to fix something, or you aren't able to get around to it, that's totally okay, just leave a comment on the pull request and we'll figure it out 💖.

Pull requests have to pass all the automated checks before they can be merged - this includes style checks, global linters, a security check, and unit tests.

Linting Hyperlink to this header

Global Hyperlink to this header

We use EditorConfig to maintain consistent indenting and line endings.

Python Hyperlink to this header

BookWyrm uses the Black code formatter to keep the Python codebase consistent styled. All new pull requests are checked with GitHub actions, and you can automatically fix code style problems by running ./bw-dev black

Code is also checked with Pylint using GitHub Actions. Pylint warnings must be addressed before pull requests are merged, but it's a judgement call if the suggestion should be used, or the warning suppressed. To suppress a warning, add a comment at the end of or on the line above the warnings: # pylint: disable=warning-name

Templates (HTML) Hyperlink to this header

Your pull request will also be checked by the curlylint linter for Django templates.

CSS Hyperlink to this header

We use stylelint to check all CSS rules. As with Pylint you can disable stylelint for a particular rule, but you will need a good justification for doing so.

JavaScript Hyperlink to this header

ESLint checks any JavaScript changes you have made. If ESLint doesn't like your working JavaScript, check the linter message for the exact problem.

Inclusive Design Hyperlink to this header

Bookwyrm aims to be as inclusive and accessible as possible.

When contributing code, check the Inclusive Web Design Checklist before you file your pull request. For accessibility advice, A11Y-101 is also a useful source. For information on how to make your page templates multi-lingual, see the Translations section.

Some particular things that Bookwyrm contributors have found useful to remember are:

Forms Hyperlink to this header

  • Only use input[type="checkbox"] or input[type="radio"] inside <label>
  • If you do not place checkboxes and radio buttons inside the <label>, the <label> should be placed after the element it relates to
  • Use a <button> element for anything that exists to trigger a JavaScript action (e.g. hiding or unhiding a form) or sends a POST request (e.g. submitting a form
  • Use an <a> element for anything that triggers a GET request. Usually, an anchor (<a>) element should not be styled as a button (class="button"), though there are some exceptions such as "Cancel" buttons. If in doubt, ask for advice in your pull request