How to contribute

Python Versions

The target version is currently Python 3.10 minimum as of 2025 and will increase at the pace of Python’s end of life.

Conda is probably the easiest way to install Python, especially when several versions are needed.

Install an editable version

  1. Clone the repository:

    git clone https://github.com/smrt-model/smrt.git cd smrt

  2. Create and activate a virtual environment

    This can be done for example with venv but please refer to https://docs.python.org/3/library/venv.html if this is new to you. Most IDE have their own way of generating virtual environments, which may be easier than using venv.:

    python -m venv .venv
source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`

  3. Install the project in editable mode:

    pip install -e . –group dev

    This command installs the package in “editable” mode, meaning any changes you make to the source code will be immediately reflected without needing to reinstall. Additional dependencies for developers are also installed.

    Note

    The group option appeared in pip25.1 while the latest stable version on 5/9/25 is pip24.0. Run pip install --upgrade pip in your local environment to get the latest version.

Git

  • The development by the core developers is done on the master branch (as of 2025), although this practice may change in the future. Other developers can either use branches (if rights granted) or use pull requests (for all users). The latter is recommended.

  • When using branches, name branches explicitly, e.g., ‘feature/changes-being-made-JD’, to avoid name conflicts with other developers.

Bug Correction

Every bug found and corrected should result in writing a unit test to prevent the bug from reappearing (regression).

Benchmarking

Benchmarking is done with Airspeed Velocity (ASV) which should be installed as a dependency for developers. Benchmarks can be run with `bash asv run ` Running ASV for the first time on a machine will ask for information on the machine. For now, benchmark results are not saved and only local comparisons can be done. Feel free to add any nuseful benchmarks.

Documentation Generation with Sphinx

The documentation is generated automatically on ReadTheDocs for the last version and the master branch. It is also possible to generate the documentation locally using Sphinx. If no new module is added, it is simple to generate the rst and HTML documentation by typing (from the smrt/doc directory):

make fullhtml

The documentation can then be accessed via the index.html page in the smrt/doc/build/html folder. It is requested to check that the documentation is well rendered after every major change.

If you have math symbols to be displayed, this can be done with the imgmath extension (already used), which generates a PNG and inserts the image at the appropriate place. You may need to set the path to LaTeX and dvipng on your system. From the source directory, this can be done with, e.g.:

sphinx-build -b html -D imgmath_latex=/sw/bin/latex -D imgmath_dvipng=/sw/bin/dvipng . ../build/html

Or to continue to use make html or make fullhtml, by setting your path (C-shell), e.g.:

set path = ($path /sw/bin)

Or for bash:

PATH=$PATH:/sw/bin

Note

Math symbols will need double backslashes in place of the single backslash used in LaTeX.

To generate a list of undocumented elements, while in the source directory:

sphinx-build -b coverage . coverage

The files will be listed in the coverage/python.txt file.