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:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards-compatible manner, and
- 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.