Development Guide

This page describes how to set up your environment for developing ccu.

Setting Up

Follow these steps to set up your local environment to develop ccu.

1. Fork ccu on GitLab (look for the “Fork” button).

2. Clone your fork locally:

   git clone git@gitlab.com:YOURGITLABNAME/python-comp-chem-utils.git
   cd python-comp-chem-utils
   

3. Install hatch (optional).[1]

4. Install ccu into a virtual environment with development extras:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install .[dev,docs,test]
   

   If hatch is installed, you can instead run:

   hatch shell
   

5. Install the pre-commit hooks (optional):[2]

   pre-commit install --hook-type pre-commit
   

Development Worklow

Follow these steps to contribute your first changes to ccu.

1. Make sure your environment is set up.

2. Create a branch for local development:

   git checkout -b name-of-your-bugfix-or-feature
   

3. Commit your changes, push them to your remote and create a new merge request (see the Merge Request Guidelines):

   git commit -m 'A descriptive commit message'
   git push origin
   

Writing Good Commit Messages

Focus on “what” changed and “why”. The “how” should be self-explanatory from the diff.

Merge Request Guidelines

If you need some code review or feedback while you’re developing the code, please create a new merge request. Before your changes can be merged, please ensure that:

1. Tests are passing (run pytest or hatch run test:test).

2. Documentation is updated when there’s new API, functionality, etc.

3. New functionality is accompanied by the appropriate unit tests.

4. CHANGELOG.rst is updated with nontrivial changes.

5. Your name is listed in AUTHORS.rst.

6. The correct branch is targeted.

   • main: bug fixes and documentation changes for the current version

   • development: new features and any breaking changes

Coding Standards

ccu closely follows the Google style guide for Python.

• All public functions must have docstrings and type-hints.

• Format your code with ruff.

• Docstrings must be written in the no-types version of Google-style docstrings.

• When writing new documentation, consider the principles of diataxis.

Code-Quality

To run code-quality checks, run:

pre-commit run --all-files

or:

hatch run quality:quality

This will run ruff and mypy along with other formatting and security checks.

Tests

ccu uses the pytest testing framework.

To run tests on the current Python version, run:

pytest

To run tests on a specific Python version (version must be present), run:

hatch run test.pyX.Y:test

where X and Y are the major and minor Python version number, respectively.

To run tests on all supported Python versions (versions must be present), run:

hatch run test:test

[1]

(hatch helps with project and environment management.)

[2]

Running the pre-commit hooks as part of the development process is recommended as it is a cheap way for you to catch errors in your code before CI.