Taurex 3 development guidelines

Overview

Here we describe the development guidelines for TauREx 3 and some advice for those wishing to contribute. Since TauREx 3 is open-source, all contributions are welcome!!!

Development on TauREx 3 should be focused on building and improving the framework. New components (i.e. chemistries, profiles etc.) are generally not built directly into the TauREx 3 codebase.

We recommend building new components as Plugins. You can refer to the Plugin Development guide.

Documentation

All standalone documentation should be written in plain text (.rst) files using reStructuredText for markup and formatting. All docstrings should follow the numpydoc format. New features must include both appropriate docstrings and any necessary standalone documentation

Unit-testing

Unittesting is important in preserving sanity and code integrity. For TauREx 3 we employ pytest. When bugfixing, ensure unittests pass.

For a direct unit test run in the root directory do:

pytest tests/

If you prefer to install the test dependencies directly with pip, use:

python -m pip install -e .[test]
pytest

If you use nox, keep in mind that running nox executes more than the unit tests. The default sessions also include formatting and linting checks, and may include additional validation such as doctest-style checks. To run only the unit test session, use:

nox --session=tests

When building new features, create new unittests and include them in the tests/ directory, any future collaborations from other developers are less likely to break your feature unexpectedly when they have something to easily test against.

Some rules:

  • No extra files should be included. Instead have the unit test generate them on the spot.

  • We recommend hypothesis for bug finding.

Coding conventions

Code should follow the PEP8 standard. This can be facilitated with a linter such as flake8. Contributors should also run pre-commit before opening a pull request, either as an installed git hook or manually from the repository root:

python -m pip install -e .[lint]
pre-commit run --all-files --hook-stage=manual

Source control

Git is the source control environment used. In particular, we follow the git-flow branching model internally. In this model, there are two long-lived branches:

  • master: used for official releases. Contributors should not need to use it or care about it

  • develop: reflects the latest integrated changes for the next release. This is the one that should be used as the base for developing new features or fixing bugs.

For contributions we employ the Fork-and-Pull model:

  1. A contributor first forks the TauREx3 repo

  2. They then clone their forked branch

  3. The contributor then commits and merges their changes into their forked develop branch

  4. A Pull-Request is created against the official develop branch

  5. Anyone interest can review and comment on the pull request, and suggest changes. The contributor can continue to commit more changes until it is approved

  6. Once approved, the code is considered ready and the pull request is merged into the official develop