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:

  with makewithout make

  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:

make docs-serve 8000

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

How the docs are organized

docs/ follows the Diátaxis framework, and each page belongs to exactly one quadrant:

When adding a page, decide which one it is first. Please do not add hand-maintained lists of methods: those belong in the API reference, which is generated from the docstrings and therefore cannot go stale.

Code blocks in the docs are executed

User guide snippets use markdown-exec, so their output is produced by actually running the code at build time rather than being written by hand:

```python exec="true" source="material-block" session="my-page" result="python"
from iso_week_date import IsoWeek

print(IsoWeek("2023-W01") + 1)
```

Blocks sharing a session name share their variables, so later blocks on a page can reuse earlier ones. Use print() rather than trailing # output comments.

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.