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.
There are several ./bw-dev commands you may find helpful for linting and testing prior to pushing your pull request. See Command Line Tool for all the options available.
We use EditorConfig to maintain consistent indenting and line endings.
BookWyrm uses ruff for both code linting (checking for errors) and formatting (ensuring code style is consistent). All new pull requests are checked with GitHub actions, and you can automatically fix code style problems by running ./bw-dev ruff. For linting errors, you can try ./bw-dev ruff-fix to automatically fix errors, though this may not always be possible.
Ruff linting 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. See the Ruff projects's documentation on suppressing warnings using code comments.
The BookWyrm project previously used Black for formatting and Pylint for linting. You may notice artefacts such as pylint suppression comments in older code. We are still refining our linting rules so if something seems confusing or not quite right, don't hesitate to ask for advice.
We are gradually rolling out static type checking across the BookWyrm code base. This is a long term project. Whilst it is not compulsory to formally define types in new code, it is strongly recommended. This will help to avoid some more subtle bugs that may not be identified in tests.
We currently use mypy as our static type checker. Find out more about how to use mypy at the mypy project documentation.
Your pull request will also be checked by the curlylint linter for Django templates.
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.
ESLint checks any JavaScript changes you have made. If ESLint doesn't like your working JavaScript, check the linter message for the exact problem.
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:
input[type="checkbox"] or input[type="radio"] inside <label><label>, the <label> should be placed after the element it relates to<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)<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 requestBookWyrm is an international project and aims to be inclusive of as many languages as possible. All user-facing messages and templates should follow the advice on translations and gendered language.