Contributing

If you want to contribute to csnake, please follow these guidelines.

Old Python versions

Csnake works with Python versions 3.6 and 3.7. It uses formatted string literals which first appear in version 3.6.

I have no interest in porting csnake to older versions of Python (especially not 2.x) and won’t take in such pull requests.

pre-commit hooks

Csnake uses an opinionated automatic code formatting setup that’s run pre-commit for every commit you’re making. This prevents contributors from wasting their time on formatting code, and also warns them about some kind of errors (via linter). The formatters’ settings are tailored to produce code that diffs clean, meaning that parts of code (arguments, from ... include ...) are split into lines.

Pre-commit hooks include:
reorder_python_imports
Reorders imports and breaks them up into lines (so they diff clean)
pyupgrade
Upgrades obsolete python syntax.
black
Formats the code in an opinionated way
flake8
Statically checks for all kinds of bugs

You are expected to run the pre-commit hooks locally before you make a pull request. All of them (along with pytest and Sphinx doctest) will be re-run by the CI server side when you commit your code, and you’ll be asked to fix the errors reported before your commit is considered for merging.

Installing the development environment

You can install (locally, in a pipenv environment) everything you need for development by running make setup in the root of the project. Python 3.6+ and pipenv are required.

This installs packages needed for formatting, pre-commit tasks, linting and testing, and also sets up the pre-commit hook.

Testing

Csnake is thoroughly tested with pytest based scripts in the tests folder.

You must thoroughly test your additions in the same way if you want your code to be merged. Your code mustn’t break any existing tests.

Tests are run by CI when you submit your pull request. You should run them locally beforehand, too.

Pytest tests can be run with the following commands (after you’ve installed the dev environment):

python -m pytest -vv

or

pytest -vv

If you’re using pipenv for development, you should activate it beforehand:

pipenv shell

There are doctests within the documentation. Its primary purpose is to provide examples, not for testing. Still, it’ll be tested by the CI for errors. Locally, you can do the same by running:

make doctest

from the docs folder.

Docs can be generated by running make html from the docs folder.

Documentation

Every public class, function and module must be documented via its docstring.

Docstrings are processed by Sphinx and its Napoleon plugin to create the API section of the documentation. Google style should be used for docstrings (see the existing docstrings, too).

Examples should be provided within the docstring in doctest format. These shouldn’t be used as a way of testing (that’s what pytest tests are for), but their correctness will be checked by the CI. Erroneous documentation is bad.

If you want to see how your docs look like or check them for errors, take a look into doc generation above.

Within the RST documentation, there’s a file that categorizes Napoleon-generated API documentation (docs/source/csnake.rst). If you’re adding functions or classes, you should indicate their categories in that file.

Versioning

Csnake uses Semantic Versioning. Here’s a short summary:

Given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards-compatible manner, and
  3. PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.