Development and TODOs

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

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

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. b2luigi is not using setuptools but the newer (and better) flit as a a builder. Install it via

   python -m pip [ --user ] install flit
   

   You can now install b2luigi from the cloned git repository in development mode:

   flit install -s
   

   Now you can start hacking and your changes will be immediately available to you.

4. Install pre-commit, which automatically checks your code

   python -m pip [ --user ] install 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. Install it via

   python -m pip install -U [ --user ] pytest pytest-cov python-coveralls
   

   All tests reside in the tests/ sub-directory. To run all tests, run the command

   pytest -v b2luigi 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 build automatically on every commit to main. You can (and should) also build the documentation locally by installing sphinx, sphinx-book-theme, sphinx-autobuild and few, additional, dependencies (note they should have already been installed when running flit install -s):

   flit install --only-deps
   

   And starting the automatic build process in the projects root folder

   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.

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. Use the bump-my-version package to update the version in b2luigi/__init__.py, .bumpversion.cfg as well as the git tag. flit will automatically use this.

      python3 -m pip install --upgrade bump-my-version
      bump-my-version bump --no-commit [patch|minor|major]
      

   3. Push the new commit and the tags

      git push
      git push --tags
      

   4. Create a new release on GitLab and on GitHub with an appropriate description.

   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. Install the dependencies with

      python -m pip install -U [ --user ] setuptools wheel twine
      

      and publish via

      flit publish
      

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.