lilio
developer documentationο
If youβre looking for user documentation, go here.
Development installο
For a full development enviroment run the commands below.
Note that this is optional: if you already have hatch
in your main environment, this setup is not needed, as you can use the hatch
environments to run all commands.
# Create a virtual environment, e.g. with
python3 -m venv env_name
# activate virtual environment
source env_name/bin/activate
# Or on windows:
# env_name/Scripts/Activate.ps1
# make sure to have a recent version of pip and hatch
python3 -m pip install --upgrade pip hatch
# (from the project root directory)
# install lilio as an editable package
python3 -m pip install --no-cache-dir --editable .
# install development dependencies
python3 -m pip install --no-cache-dir --editable .[dev]
Afterwards check that the install directory is present in the PATH
environment variable.
Running the testsο
Lilio uses pytest
for unit testing. Running tests has been configured using hatch
, and can be started by running:
hatch run test
In addition to just running the tests to see if they pass, they can be used for coverage statistics, i.e. to determine how much of the packageβs code is actually executed during tests. Inside the package directory, run:
hatch run coverage
This runs tests and prints the results to the command line, as well as storing the result in a coverage.xml
file (for analysis by, e.g. SonarCloud).
Running linters locallyο
For linting and code style we use ruff
. We additionally use mypy
to check the type hints.
All tools can simply be run by doing:
hatch run lint
To comply with formatting you can run:
hatch run format
Generating the documentationο
To generate the documentation, simply run the following command. This will also test the documentation code snippets. Note that you might need to install pandoc
to be able to generate the documentation.
hatch run docs:build
The documentation will be in docs/_build/html
.
You can also make use of the sphinx-autobuild plugin to show a live preview of the documentation, which can make developing the documentation a bit easier.
Versioningο
Firstly, determine what new version (major, minor or patch) to use. This package uses semantic versioning <https://semver.org>
. Bumping the version across all files is done with bumpversion, e.g.
bumpversion major
bumpversion minor
bumpversion patch
Making a releaseο
This section describes how to make a release in 3 parts: preparation, release and validation.
Preparationο
Update the
CHANGELOG.md
file with changes between current and new version.Verify that the information in
CITATION.cff
is correct.Make sure the version has been updated.
Run the unit tests with
hatch run test
.Commit & push changes to GitHub.
Wait for GitHub actions to be completed and green.
Making the GitHub releaseο
Create a new GitHub release
- Use version as title and tag version.
- Summarise the changes in this new release (to give context to
Zenodo record) and then add changes from `CHANGELOG.md`
This will:
trigger Zenodo into making a snapshot of your repository and sticking a DOI on it.
start a GitHub action that builds and uploads the new version to PyPI.
Which should trigger conda-forge to update the package as well.
Validationο
After making the release, you should check that:
The Zenodo page is updated
The publishing action ran successfully, and that
pip install lilio
installs the new version.The conda-forge package is updated, and can be installed using conda.