How to contribute?

If you have installed tensorwaves 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 git@github.com:ComPWA/tensorwaves.git
code tensorwaves
conda env create
pip install -e .[dev]

For more info, see Visual Studio code.

When working on the source code of tensorwaves, it is highly recommended to install certain additional Python tools. Assuming you installed tensorwaves 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, 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=tensorwaves

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 tensorwaves.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 or fix: 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.

  2. A definition of __all__, so that you can see immediately what this Python file defines, followed by two empty lines.

  3. Only after these come the import statements, following the PEP 8 conventions for imports.

• 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.