Contributing and Developing

Organization

This repository is built to use setuptools. It is organized according to setuptools src layout style.

Work Flow

  • Go to Issues and raise a new issue. Choose the Issue template (bug, feature, etc, under .gitlab/issue_templates/) that is most appropriate, and fill in the requested sections.
  • Create a Merge Request, which automatically creates the associated branch.
  • Fix the problem, or ask for help, on that branch.
  • When the fix is complete, increment the version (following semantic versioning) in pyproject.toml and update the CHANGELOG.md detailing the high-level changes to the code. For more information on the changelog, see https://keepachangelog.com/.
  • On the Merge Request, click the “Mark as ready” button and tag someone else to review your Merge Request.
  • A maintainer will make sure that the branch pipeline passes entirely before merging.
  • After merging, a maintainter will make sure that the main pipeline passes entirely after merging.

Installation

End-user’s Installation

See the README.md.

Developer’s Installation

The following will replicate the setup in the CI/CD environment:

$ cd <path/to/dimmer>
# activate a virtual env. With conda or uv or pixi or python's venv shown here:
$ python -m venv .venv
$ source .venv/bin/activate
$ pip install -e ".[testing,docs]"

Any of the optional dependency tables from pyproject.toml can be installed this way. E.g. to include just formatting and linting, but not testing or docs:

    $ pip install -e ".[formatting]"

Testing

The following will run the unit tests on the package:

$ cd <path/to/dimmer>
$ source .venv/bin/activate
$ pytest

Software Versioning

A changelog is maintained. As the code evolves, this file should update accordingly with information about added features, deprecations, and bug fixes.

When enough progress has been made or a big enough future change is planned, a version of the code should be tagged.

For more on versioning expectations and how to structure the changelog, see the links in the changelog document.

The version number should be changed accordingly in pyproject.toml.

Formatting and linting

Ruff is used for linting and formatting code.

Linting

Linting refers to a static analysis of the codebase to check for efficient and compliant python code. The default rules are documented in the pyproject.toml files. Linting with ruff can be performed from the command line via ruff check. Ruff can also be installed in an IDE to make this simpler. Certain errors in ruff can be automatically fixed by running ruff check --fix. Any errors that pop up (e.g. E401) can be expanded on by executing ruff rule <error>, as in ruff rule E401.

Formatting

Formatting refers to adjusting the physical appearance of the code (adding new lines, commas, etc.), without modifying any of the intent or logic. Ruff can automatically format a specific file by executing ruff format <path>/<to>/<file> or everything from the cwd with ruff format.

Documentation

Viewing Docs

Published documentation is available at https://marcelintel.gitlab.io/dimmer.

Building Docs Locally

Once the repo is cloned, quarto documentation can be built after installing quarto with the following commands

$ cd <path/to/dimmer>
$ source .venv/bin/activate
$ ./build_docs.sh preview # optional, to preview docs in a browser. Allows warnings.
$ ./build_docs.sh  # to build docs in data/public/.  Stops on warnings.

To configure this project’s Quarto Documentation, please edit docs/_quarto.yml.

Publishing Code and Docs

Documentation and software wheels are exclusively deployed through CI/CD.