Skip to content

Latest commit

 

History

History
90 lines (53 loc) · 2.19 KB

CONTRIBUTING.md

File metadata and controls

90 lines (53 loc) · 2.19 KB
Raw

Contributing

Markdown code in this repo must pass several static analysis tests, which are detailed below. Note that you can run:

make ci

to run these checks before pushing to Github.

Git commit subjects

Git commit subjects must:

  • Be no longer than 70 characters;
  • Start with a capital letter;
  • Not end with a full stop;

Further, pull request branches should rebase off main to incorporate upstream changes; don't merge main into your branch.

These rules are checked using Pytest in CI.

Formatting

All markdown should be formatted with Prettier version 3.0.0 This can be installed on your host OS with:

npm install -g prettier@3.0.0

Once installed, ensure your editor runs Prettier on a pre-save hook:

Prettier conformance is checked in CI and configured via .prettierrc.yaml and .prettierignore.

Spelling

Pull requests must pass a spell-check before merge. This is done using the tmaier/markdown-spellcheck Docker image.

To run the spell-test locally run:

make spell_check

or:

docker run --rm -ti -v $(pwd):/workdir tmaier/markdown-spellcheck:latest \
    --report --ignore-numbers --ignore-acronyms "**/*.md"

Add exceptions to the custom dictionary in .spelling.

Linting

Markdown files are linted by markdownlint-cli.

To run the linting locally run:

docker run -i --rm -v `pwd`:/work tmknom/markdownlint:0.33.0

or, if installed on your host OS, run:

markdownlint .

or:

make markdownlint

Configuration for the enforced rules is in .markdownlint.yaml.

Many linting issues can be fixed by running:

markdownlint --fix .

Preview rendered pages

You can use grip to render Github-flavour markdown files. Install with:

brew install grip

While working on docs, run a local, auto-reloading server with:

make server