Development Guide

Setup

Follow these steps to configure your machine for CompChemUtils development.

  1. Fork CompChemUtils (look for the “Fork” button).

  2. Clone your fork locally:

    git clone git@gitlab.com:YOURGITLABNAME/ccu.git

  3. Install poetry (optional):

    pipx install poetry

  4. Install the development environment with all extras. with poetry:

    poetry install --with=dev,vcs,docs,format-lint,type_check

    with pip:

    python3 -m pip install .[dev,vcs,docs,format-lint,type_check]

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

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

  6. Create a branch for local development:

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

Now you can make your changes locally.

Merge Request Guidelines

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

  1. Tests are passing (run nox).

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

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

  4. Add a note to CHANGELOG.rst about the changes.

  5. Add yourself to 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

  7. Commit your changes and push your branch to GitLab:

    git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature

  8. Submit a merge request through the GitLab website.

Tips

To run a subset of tests:

nox -s envname

To view all testing environments:

nox -l

To run all the test environments in parallel:

nox -p auto

To format the code (ruff):

nox -s format_fix

To build the documentation:

nox -s docs