Contributing guidelines
Everyone is welcome to contribute to the code of this plugin, however we have some automation and guidelines you should get familiar with first.
PR Guidelines
Fork branch from
develop
.Ensure to provide unit tests for new functionality.
Install dev requirements:
pip install -r requirements-dev.txt
and setup a hook:pre-commit install
For commits we follow angular commit messages guideline.
Update documentation accordingly.
Update changelog according to “Keep a changelog” guidelines.
Squash changes with a single commit as much as possible and ensure verbose PR name.
Open a PR against
develop
We reserve the right to take over and modify or abandon PRs that do not match the workflow or are abandoned.
Updating the documentation
For documentation updates we have docs/Makefile
that runs Sphinx
to update the readthedocs.
There is automation using github actions that checks the spelling of the docs. Links, inline blocks escaped with back ticks
`…` and
triple backtick blocks
are omitted.
In order to add new spelling exceptions, append them to the docs/spellcheck_exceptions.txt
file.
For documentation syntax, we use Markdown with myst parser.
Templating
We have jinja
available to be used in documentation. The variables are defined in docs/conf.py
in myst_substitutions
. By default the following are available:
release
- the package version with which it was builtreq_<package>
- the specification of version package requirement range insetup.py
req_lower_<package>
- the specification of version package requirement lower bound insetup.py
req_upper_<package>
- the specification of version package requirement upper bound insetup.py
req_build_<package>
- the specification of version package with which it was built
The templates do not work inside code fences or links. You can workaround that by putting whole code fence inside jinja
and then use the formatting inside. See the substitution documentation for details.
Warning
The substitutions do not seem to be fully jinja2
capable. While expressions {{ }}
do work, the control statements {% %}
do not.
Pre-commit and github hooks
For linting and keeping code clean we use pre-commit package to join with github hooks. Use it by doing:
$ pip install pre-commit
$ pre-commit install
You can test github actions locally with act.
Release workflow
Create the release candidate:
Go to the Prepare release action.
Click “Run workflow”
Enter the part of the version to bump (one of
<major>.<minor>.<patch>
). Minor (x.x.x) is a default.
If the workflow has run successfully:
Go to the newly opened PR named
Release candidate <version>
Check that changelog and version have been properly updated. If not pull the branch and apply manual changes if necessary.
Merge the PR to master
Checkout the Publish workflow to see if:
The package has been uploaded on PyPI successfully
The changes have been merged back to develop