Contributing
Thank you for helping with markright. This document says how a change gets in; Development says how the code is built, checked and released.
Before you start#
- A bug: open an issue with the document, or the smallest part of it, that shows the problem, the command you ran, what markright printed or changed, and what you expected. Say which version
markright versionprints. - A new rule or setting: open an issue first. Describe what it reports or rewrites, with a document it changes and the same document after, and why a renderer reads the two alike, for a formatter, or why the first is a mistake, for a linter. A rule that would report much of what people write on purpose fits better as a setting of an existing one, or not at all.
- A fix to the documentation: a pull request is enough.
Making the change#
Branch from
main, in a fork or, with write access, in the repository itself. Name the branch after the change, its type first:feat/list-indent,fix/anchors-in-tables,docs/configuration-examples.Make the change with its tests. A new formatter or linter follows Development: Adding a formatter or linter.
Update the documents the change touches: a new term goes in GLOSSARY.md, a new document in CONTENTS.md, and a specification the tool starts to follow in STANDARDS.md.
Run every check, as CI does:
bash scripts/check.shWhen the change touches the site, build it and check its links as well: Development: The documentation site.
Commits and pull requests#
Commit messages follow Conventional Commits: a type, a colon and what the commit does, in the imperative and in lower case.
| Type | For |
|---|---|
feat | a new rule, setting, command or output |
fix | a rule that reports or rewrites what it should not |
docs | the documentation only |
refactor | a change of the code that changes no behaviour |
test | tests only |
build | the toolchain, dependencies, scripts and CI |
A change that breaks configurations that work today adds ! after the type, as feat!:, and says what to change in its body.
Every change reaches main through a pull request, the maintainers' own included; main takes no direct pushes. A pull request does one thing, says why, and needs the Check and Site jobs of CI to pass before it is merged. It is squash-merged, so its title, written as a commit message above, becomes the one commit on main and the line of the release notes that names the change.
License#
By contributing, you agree that your contribution is released under the MIT License, as the rest of markright.