Contributing

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

Quick access to coverage report and test results

Quick overview of goals and non-goals

Old Python versions

Csnake works with Python versions 3.6, 3.7 and 3.8. 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.

Windows

I don’t use Windows or own a Windows licence. Currently, there are no Windows tests and a Windows installer isn’t being built.

If You’d like to help with Windows support, please add a suite of Windows-specific tests and a full deployment pipeline.

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

check-vcs-permalinks

Ensures that all VCS links are permalinks

check-merge-conflict

Checks for version conflict strings

yesqa

Warns about unneeded noqa comments.

blacken-docs

Applies Black to any code within docs.

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 pull request is considered for merging.

Pre-commit hook installation is explained below.

Installing the development environment

You can install (locally, in a poetry environment) everything you need for development by running make setup in the root of the project. Python 3.6+ and poetry 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 (relatively) thoroughly tested with pytest based scripts in the tests folder. Test coverage is being tracked here.

You should thoroughly test your additions in the same way before submitting a pull request. 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

PYTHONPATH=. pytest -vv

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

poetry shell

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

cd docs
make doctest

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/api.rst). If you’re adding functions or classes, you should indicate their categories in that file.

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

cd docs
make html

Online, the compiled Sphinx html documentation can be viewed on the GitLab pages page for this package.

The documentation html is compiled by the CI from the master branch.

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.

Version info is inferred from git tags by using Versioneer.