Development
This section gives on overview about everything you need to know if you wish to contribute to bmlab or BMicro.
Development workflow
We use GitHub projects to manage the development workflow of bmlab and BMicro. The main development project board is Brillouin Evaluation in Python.
The development is split into “User Stories”, each of which is a collection of issues (identified via titles in the issues). The current work in progress (WIP) branch is named according to the currently active user story (e.g. 1-smoke-test). Issues that are not part of the current user story should still be addressed in the current WIP branch.
Once you wish to address an issue, drag it from the “Open” or “Ready” column of the project board to the “In progress” column. Once you finished working on an issue, drag it to the “Done” column, but don’t close it yet (It should be discussed first in the dev meeting).
Notes:
Documentation
It is always helpful to have code examples and thorough descriptions
in a documentation. We use sphinx-autodoc for the
code reference, which means that the docstrings
of your functions and classes are automatically rendered. Please
make sure that this is working properly - go to the docs
directory
and execute:
pip install -r requirements.txt
sphinx-build . _build
This will create a a file _build/index.html
which you can open in
your favorite browser. This also applies to bmlab.
Tests
We try to adhere to test-driven development. Please always write test functions for your code. Make sure you have the required packages installed:
pip install -r tests/requirements.txt
You can run all tests via
python -m pytest tests
To check for code coverage, make sure the coverage Python package is installed and run
coverage run --source="bmicro" -m pytest tests
coverage report
Making a new release
The release process of BMicro is completely automated. All you need to know is that you have to create an incremental tag:
git tag -a "0.1.3"
# or (if you have set up PGP)
git tag -s "0.1.3"
# and finally
git push --tags
For more information on how automatic deployment to PyPI works, please read on.
Continuous integration
The following things are automated:
pytest and flake8 on Linux, macOS, and Windows via GitHub Actions: https://github.com/BrillouinMicroscopy/BMicro/actions?query=workflow%3AChecks
You should always check that all checks pass before you merge a pull request (A green state on your local machine does not mean a global green state).
automatic deployment to PyPI on tag creation via GitHub Actions: https://github.com/BrillouinMicroscopy/BMicro/actions?query=workflow%3A%22Release+to+PyPI%22
Paul Müller created the BMicro package on PyPI and gave the user
ci_bm
permission to upload new releases. The password for this user is an organization secret.documentation is built automatically (for all tags and for the latest commit to the main branch) on readthedocs: https://readthedocs.org/projects/BMicro/builds/
coverage statistics are done with codecov: https://codecov.io/gh/BrillouinMicroscopy/BMicro
Please try stay above 90% coverage.
Badges for all of these CI tasks are in the main README.rst
file.