Skip to content

Latest commit

 

History

History
123 lines (92 loc) · 5.01 KB

Contributing.md

File metadata and controls

123 lines (92 loc) · 5.01 KB
Raw

Contributing to ReadAlong Studio

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.
  • commitlint is used as a commit message hook to validate that commit messages follow the convention.

TL;DR

Run these commands in each of your sandboxes to enable our pre-commit hooks and commitlint:

pip install -r requirements.dev.txt
pre-commit install
gitlint install-hook

Pre-commit hooks

The ReadAlong Studio team has agreed to systematically use a number of pre-commit hooks to normalize formatting of code. You need to install and enable pre-commit 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

Enabling pre-commit hooks

All the pre-commit hooks are executed using a tool called pre-commit. Once you enable pre-commit, it will run all the hooks each time you try to commit anything in this repo.

We've listed all the developper dependencies for the project in requirements.dev.txt to make them easy to install:

pip install -r requirements.dev.txt
pre-commit install

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

commitlint

The team has also agreed to use Conventional Commits. Install and enable gitlint to have your commit messages scanned automatically.

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:

Enabling commitlint

You can run commitlint on each commit message that you write by enabling the commit-msg hook in Git.

Run this command in your g2p sandbox to install and enable the commit-msg hook:

pip install -r requirements/requirements.dev.txt
gitlint install-hook
  • Now, next time you make a change and commit it, your commit log will be checked:
    • git commit -m'non-compliant commit log text' outputs an error
    • git commit -m'fix(g2p): fixing a bug in g2p integration' works