Contributing to MotherTongues¶

Guides here are intended to help developers set up their environment for making contributions back to the Mother Tongues code. None of these guides are required to successfully install, customize or run Mother Tongues dictionaries, so if you're not planning on contributing, feel free to skip these guides.

Feel free to dive in! Open an issue or submit PRs.

This repo follows the Contributor Covenant Code of Conduct.

This repo uses automated tools to standardize the formatting of code, text files and commits.

Pre-commit hooks validate and automatically apply code formatting rules.
gitlint is used as a commit message hook to validate that commit messages follow the convention.

Set up Pre-commit Hooks¶

You will need to pip install these packages in each environment:

Then run the following commands in each of your python environments to enable our pre-commit hooks and commitlint:

pre-commit install
gitlint install-hook
git submodule foreach 'pre-commit install'
git submodule foreach 'gitlint install-hook'

And you're ready to start contributing!

Important

You have to run the second command in every sandbox you create, so please don't forget to do so when you clone a new sandbox!

Enforced Commit Message Formatting¶

Contributions to mothertongues will only be accepted if commit messages conform to Conventional Commits.

Luckily, one of the pre-commit hooks you just installed will validate this locally for you!

Convential commits look like this:

type(optional-scope): subject (i.e., short description)

optional body, which is free form

optional footer

Valid types: (these are the default, which we're using as is for now)

build: commits for the build system
chore: maintain the repo, not the code itself
ci: commits for the continuous integration system
docs: adding and changing documentation
feat: adding a new feature
fix: fixing something
perf: improving performance
refactor: refactor code
revert: undo a previous change
style: working only on code or documentation style
test: commits for testing code

Valid scopes: the scope is optional and usually refers to which module is being changed.

TBD - for now not validated, should be just one word ideally

Valid subject: short, free form, what the commit is about in less than 50 or 60 characters (not strictly enforced, but it's best to keep it short)

Optional body: this is where you put all the verbose details you want about the commit, or nothing at all if the subject already says it all. Must be separated by a blank line from the subject. Explain what the changes are, why you're doing them, etc, as necessary.

Optional footer: separated from the body (or subject if body is empty) by a blank line, lists reference (e.g.: "Closes #12" "Ref #24") or warns of breaking changes (e.g., "BREAKING CHANGE: explanation").

These rules are inspired by these commit formatting guides:

More Info About the Pre-commit Hooks¶

We systematically use a number of pre-commit hooks to normalize formatting of code. Follow the installation steps above to have these used automatically when you do your own commits.

Pre-commit hooks enabled:

check-yaml validates YAML files
end-of-file-fixer makes sure each text file ends with exactly one newline character
trailing-whitespace removes superfluous whitespace at the end of lines in text files
Flake8 enforces good Python style rules; more info about using Flake8 in pre-commit hooks at: Lj Miranda flake8 blog post
isort orders python imports in a standard way
Black, the Uncompromising Code Formatter, refortmats all Python code according to very strict rules we've agreed to follow; more info about Black formatting rules in The Black code style
mypy runs type checking for any statically-typed Python code in the repo