Development and TODOs

You want to help developing b2luigi? Great! Have your GitHub or DESY GitLab account ready and let’s go!

If you are a Belle II collaborator, you can contribute directly on the _.

Local Development

You want to help developing b2luigi? Great! Here are some first steps to help you dive in:

1. Make sure you uninstall b2luigi if you have installed if from PyPI

   python -m pip uninstall b2luigi
   

2. Clone the repository from GitHub

   git clone https://github.com/belle2/b2luigi
   

   or, for Belle II collaborators, clone the repository from DESY GitLab

   git clone git@gitlab.desy.de:belle2/software/b2luigi.git
   

3. Change into the cloned directory

   cd b2luigi
   

   We recommend to work only in Python virtual environments. You can create a new virtual environment with

   python3 -m venv venv
   

   and activate it with

   source venv/bin/activate
   

   If you are a Belle II collaborator, you can also use the b2venv command to create a virtual environment.

3. b2luigi uses uv for dependency management, building and publishing. Install it via

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   You can now install b2luigi from the cloned git repository in development mode, together with the test and documentation tooling:

   uv sync --group dev --extra tui
   

   This creates a .venv in the repository (or fills the active virtual environment with --active) and installs b2luigi in editable mode, so your changes are immediately available to you.

4. Automatically check your code with pre-commit:

   pre-commit install  # install the pre-commit hooks
   pre-commit run --all-files  # run pre-commit manually
   

   In particular, the python files are checked with ruff for syntax and PEP 8 style errors. We recommend using an IDE or editor which automatically highlights errors with ruff or a similar python linter (e.g. Pylint or flake8).

5. We use the pytest package for testing some parts of the code. All tests reside in the tests/ sub-directory. To run all tests, run the command

   uv run pytest -v tests
   

   in the root of b2luigi repository. If you add some functionality, try to add some tests for it.

6. The documentation is hosted on b2luigi.belle2.org and built automatically. You can (and should) also build the documentation locally:

   uv run sphinx-autobuild docs build
   

   The autobuild will rebuild the project whenever you change something. It displays a URL where to find the created docs now (most likely http://127.0.0.1:8000). Please make sure the documentation looks fine before creating a pull request.

   The published documentation is versioned: the website serves the newest release at its root, the development version of main under /dev/ and, under /vX.Y.Z/, the newest patch release of every minor version since 1.0 plus the second newest one of the current minor version, with a version switcher in the sidebar. sphinx-polyversion builds every published version from a checkout of main; which versions are published is decided in docs/_polyversion/policy.py. Every version is built in its own locked environment, which uv creates with the Python version the policy assigns to it (downloading that Python if necessary): from the uv.lock of the version or, for the releases up to v1.2.9 that have none, from the requirements file of its minor version in docs/_polyversion/requirements. To build the complete website locally and serve it:

   uv run sphinx-polyversion docs/poly.py -o BASE_URL=http://localhost:8000/
   python -m http.server -d _docs_build 8000
   

   uv run sphinx-polyversion docs/poly.py --local builds only your working tree (as dev), which is what the CI pipeline does.

7. If you are a core developer and want to release a new version:

   1. Make sure all changes are committed and merged on main

   2. Bump the version in pyproject.toml (the single source; b2luigi.__version__ reads it from the installed metadata):

      uv version --bump [patch|minor|major]
      

      uv version updates pyproject.toml and uv.lock but does not commit or tag, so do that yourself:

      git commit -am "Bump version: <old> → <new>"
      git tag v<new>
      

      Use uv version --bump minor --dry-run to preview the change.

   3. Push the new commit and the tag

      git push --follow-tags
      

   4. On GitLab releases are automatically generated from the merge requests that had a title and a changelog in their description.

      For GitHub create a release and copy the content from GitLab.

   5. Check that the new release had been published to PyPI, which should happen automatically via GitLab pipeline. Alternatively, you can also manually publish a release:

      uv build && UV_PUBLISH_TOKEN=<pypi-token> uv publish
      

      To rehearse the publishing process, publish to TestPyPI first (configured as the testpypi index in pyproject.toml); the pipeline offers this as a manual job:

      UV_PUBLISH_TOKEN=<test-token> uv publish --index testpypi
      

Open TODOs

For the Belle II collaborators: for a list of potential features, improvements and bugfixes see the GitLab issues. Help is welcome, so feel free to pick one, e.g. with the good first issue or help wanted tags.