Contributing

August 9, 2026 ยท View on GitHub

Setup

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

If you want to work on the documentation site:

pip install -e ".[docs]"

Local Checks

Run lint and tests before opening a pull request:

ruff check .
pytest -q

If documentation dependencies are installed, preview docs locally:

zensical serve

Change Expectations

  • Keep the runtime package dependency free.
  • Add tests for behavior changes and bug fixes.
  • Preserve backwards compatibility for public APIs unless the change is explicitly scheduled for a major release.
  • Update README.md and docs/ when behavior or public interfaces change. Release history lives in git tags / GitHub Releases (no CHANGELOG.md).

Pull Requests

  • Keep PRs scoped to one logical change.
  • Describe user-visible impact clearly.
  • Include migration notes when behavior changes.