Contributing to rtflite¶

Developer workflow¶

Setup¶

First off, install uv. rtflite uses uv to manage the Python package development environment.

If you have trouble installing the exact Python version pinned in the project, run

uv self update

to update your uv installation.

Branching¶

Clone the repository (if you have no direct access, replace the address with your forked repository address):

git clone https://github.com/pharmaverse/rtflite.git

Create a dedicated branch:

cd rtflite
git checkout -b my-branch

Dependencies¶

Restore the environment using uv sync. This will restore the exact versions of Python and dependency packages under the project's .venv/ directory:

uv sync

Development¶

Open the project in VS Code:

code rtflite

Make changes to the codebase.

We use pytest for unit testing. To run tests and get an HTML preview of code coverage, open the VS Code terminal:

pytest
pytest tests/specific_test.py
pytest --cov=rtflite --cov-report=html:docs/coverage/

Virtual environment activation

If your terminal did not activate the virtual environment for some reason (with symptoms like not finding pytest commands), activate it manually:

source .venv/bin/activate

Documentation¶

To preview the mkdocs website locally:

mkdocs serve

To build the mkdocs website locally into site/, run:

mkdocs build

rtflite renders vignette-like articles under docs/articlesusing markdown-exec. This allows mkdocs to render Python code chunks and their outputs when building the site. Check the markdown-exec documentation for possible code chunk options.

If you made changes to the .md files in the root directory, make sure to synchronize them to the mkdocs website:

sh docs/scripts/sync.sh

Formatting¶

Use isort and ruff to sort imports and format Python code:

isort .
ruff format

Pull request¶

Add, commit, and push to remote, then send a pull request:

git add -A
git commit -m "Your commit message"
git push origin my-branch

Maintainer workflow¶

Updates¶

Update local uv version:

uv self update

Update uv.lock file regularly:

uv sync --quiet
uv lock --upgrade
uv sync

Python version¶

Pin a newer Python version in .python-version when appropriate:

uv python pin x.y.z

The latest Python release versions are often promptly supported by uv.

Publishing¶

Publish on PyPI (maintainer token required):

uv build
uv publish