How to contribute?¶
If you have installed the expertsystem
in Development mode, it
is easy to tweak the source code and try out new ideas immediately, because the
source code is considered the ‘installation’.
Note
The easiest way to contribute, is by using Conda and Visual Studio code. In that case, the complete developer install procedure becomes:
git clone https://github.com/ComPWA/expertsystem.git
code expertsystem
conda env create
conda activate es
pip install -e .[dev]
For more info, see Visual Studio code.
When working on the source code of the expertsystem
, it is highly recommended
to install certain additional Python tools. Assuming you installed the
expertsystem
in development mode, these
additional tools can be installed into your virtual environment in one go:
pip install -e .[dev]
Most of the tools that are installed with this command use specific configuration files (e.g. pyproject.toml for black, .pylintrc for pylint, and tox.ini for flake8 and pydocstyle). These config files define our convention policies. If you run into persistent linting errors this may mean we need to further specify our conventions. In that case, it’s best to create an issue and propose a policy change that can then be formulated in the config files.
Pre-commit¶
All style checks are enforced through a tool called pre-commit. This tool needs to be activated, but only once after you clone the repository:
pre-commit install
Upon committing, pre-commit
now runs a set of checks as defined in the
file .pre-commit-config.yaml
over all staged files. You can also quickly run all checks over all indexed
files in the repository with the command:
pre-commit run -a
This command is also run on Travis CI whenever you submit a pull request, ensuring that all files in the repository follow the conventions set in the config files of these tools.
Testing¶
More thorough checks (that is, runtime tests) can be run in one go with the command
tox
This command will run pytest
, check for test coverage, build the
documentation, and verify cross-references in the documentation and the API.
It’s especially recommended to run tox before submitting a pull request!
More specialized tox
tests are defined in the tox.ini file, under
each testenv
.
Try to keep test coverage high. You can compute current coverage by running
pytest \
--cov-report=html \
--cov-report=xml \
--cov=expertsystem
and opening htmlcov/index.html
in a browser. In VScode, you can
visualize which lines in the code base are covered by tests with the Coverage
Gutters
extension (for this you need to run pytest
with the flag
--cov-report=xml
).
Documentation¶
The documentation that you find on expertsystem.rtfd.io are built from the documentation source code
folder (doc
)
with Sphinx. Sphinx also builds the API and
therefore checks whether the docstrings in the Python source code are
valid and correctly interlinked.
You can quickly build the documentation from the root directory of this repository with the command:
tox -e doc
If you want to render the output of the Jupyter notebook examples, this can be done with:
tox -e docnb
This takes more time than tox -e doc
, because it will execute the
notebooks. Alternatively, you can run sphinx-build
yourself as follows:
cd doc
make html # or NBSPHINX_EXECUTE= make html
A nice feature of Read the Docs, where we host our documentation, is that documentation is built for each pull request as well. This means that you can view the documentation for your changes as well. For more info, see here, or just click “details” under the RTD check once you submit your PR.
Spelling¶
Throughout this repository, we follow American English (en-us) spelling conventions. As a tool, we use cSpell because it allows to check variable names in camel case and snake case. This way, a spelling checker helps you in avoid mistakes in the code as well!
Accepted words are tracked through the cspell.json
file. As with the
other config files, cspell.json
formulates our conventions with regard
to spelling and can be continuously updated while our code base develops. In
the file, the words
section lists words that you want to see as
suggested corrections, while ignoreWords
are just the words that won’t
be flagged. Try to be sparse in adding words: if some word is just specific to
one file, you can ignore it inline, or you can add the file to the
ignorePaths
section if you want to ignore it completely.
It is easiest to use cSpell in Visual Studio code, through
the Code Spell Checker
extension: it provides linting, suggests corrections from the words
section, and enables you to quickly add or ignore words through the
cspell.json
file. Alternatively, you can run cSpell on the entire code base
(with cspell $(git ls-files)
), but for that your system requires npm.
Git¶
Please use conventional commit messages: start the commit with a semantic keyword (see e.g. Angular or these examples, followed by a column, then the message. The message itself should be in imperative mood — just imagine the commit to give a command to the code framework. So for instance:
feat: add coverage report tools
orfix: remove ...
.In the master branch, each commit should compile and be tested. In your own branches, it is recommended to commit frequently (WIP keyword), but squash those commits upon submitting a merge request.
Python conventions¶
Follow PEP 8 conventions.
Any Python file that’s part of a module should contain (in this order):
1. A docstring describing what the file contains and does, followed by two empty lines.
When calling or defining multiple arguments of a function and multiple entries in a data container, split the entries over multiple lines and end the last entry with a comma, like so:
__all__ = [ 'core', 'optimizer', 'physics', 'plot', ]
This is to facilitate eventual diff comparisons in Git.
Visual Studio code¶
We recommend using Visual Studio Code as it’s free, regularly updated, and very flexible through it’s wide offer of user extensions.
If you add or open this repository as a VSCode workspace, the file
.vscode/settings.json
will ensure that you have the right developer settings for this repository. In
addition, VSCode will automatically recommend you to install a number of
extensions that we use when working on this code base (they are defined
.vscode/extensions.json
file).
You can still specify your own settings in either the user or encompassing workspace settings, as the VSCode settings that come with this are folder settings.