.. _development-label: 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 .. code-block:: bash python -m pip uninstall b2luigi 2. Clone the repository from GitHub .. code-block:: bash git clone https://github.com/belle2/b2luigi or, for Belle II collaborators, clone the repository from DESY GitLab .. code-block:: bash 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 .. code-block:: bash python -m pip [ --user ] install flit You can now install ``b2luigi`` from the cloned git repository in development mode: .. code-block:: bash 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 .. code-block:: bash 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 .. code-block:: bash 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 .. code-block:: bash 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``): .. code-block:: bash flit install --only-deps And starting the automatic build process in the projects root folder .. code-block:: bash 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: a. Make sure all changes are committed and merged on main b. 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. .. code-block:: bash python3 -m pip install --upgrade bump-my-version bump-my-version bump --no-commit [patch|minor|major] c. Push the new commit and the tags .. code-block:: bash git push git push --tags d. Create a new release on `GitLab `_ and on `GitHub `_ with an appropriate description. e. 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 .. code-block:: bash python -m pip install -U [ --user ] setuptools wheel twine and publish via .. code-block:: bash 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. .. _flit: https://pypi.org/project/flit/ .. _gitlab issues: https://gitlab.desy.de/belle2/software/b2luigi/-/issues .. _pytest: https://docs.pytest.org/ .. _b2luigi.belle2.org: https://b2luigi.belle2.org .. _pre-commit: https://pre-commit.com .. _ruff: https://docs.astral.sh/ruff/ .. _PEP 8: https://www.python.org/dev/peps/pep-0008/ .. _bump-my-version: https://github.com/callowayproject/bump-my-version .. _release: https://github.com/belle2/b2luigi/releases .. _pipeline: https://github.com/belle2/b2luigi/blob/main/.gitlab-ci.yml .. _Keep a Changelog: https://keepachangelog.com/en/1.0.0/