Skip to content

Contributing

We welcome contributions to the library!

If you have a new feature and/or a bug fix that you would like to contribute, please follow the steps below.

Prerequisites

The following tools are needed as a one time setup:

  • uv for dependency management.
  • prek for pre-commit hooks.

Getting started

  1. Fork and clone the repository:

    git clone git@github.com:<your-github-handle>/iso-week-date.git
cd iso-week-date

  2. Install dependencies (including all optional and development groups):

    uv sync --all-extras --group local-dev

  3. Install the pre-commit hooks:

    prek install
prek run --all-files

    This installs git hooks under the .git/hooks/ directory and runs them on all files to verify the setup.

Development workflow

  1. Create a new branch for your bug fix or feature.
  2. Make your changes and test them thoroughly, making sure that all existing tests still pass.
  3. Commit your changes and push the branch to your fork.
  4. Open a pull request on the main repository.

Code and Markdown formatting

iso-week-date uses ruff as linter and formatter, and rumdl as markdown linter:

make lint

uvx ruff format src tests
uvx ruff check src tests --fix
uvx rumdl check .

Testing

Once you are done with changes, you should:

  • Add tests for the new features in the tests/ folder.

  • Make sure that new features do not break existing codebase by running tests:

    make test

    uv run --group tests pytest src tests --cov=src --cov=tests --cov-fail-under=95 --doctest-modules --cache-clear

Type checking

The project uses both mypy and pyright for static type checking:

make typing

uv run --group typing mypy src tests
uv run --group typing pyright src tests

Running all checks

To run linting, tests, type checking, and more in one go:

make check

Docs

The documentation is generated using zensical, the API part uses mkdocstrings.

If a breaking feature is developed, then we suggest to update the documentation in the docs/ folder as well, in order to describe how this can be used from a user perspective.

To serve it locally:

uv run --group docs zensical serve -a localhost:<port-number>

Reporting bugs

If you find a bug in the library, please report it by opening an issue on GitHub. Be sure to include the version of the library you're using, as well as any error messages or tracebacks and a reproducible example.

Requesting features

If you have a suggestion for a new feature, please open an issue on GitHub. Be sure to explain the problem that you're trying to solve and how you think the feature would solve it.

Code of conduct

All contributors are expected to follow the project's code of conduct, which is based on the Contributor Covenant.