Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
100 lines (72 loc) · 2.9 KB

CONTRIBUTING.md

File metadata and controls

100 lines (72 loc) · 2.9 KB
Raw

Contributing Guide

Development

Environment setup

Development uses devbox to provide a reproducible, isolated shell with all required tools (Python 3.12, uv, just, taskwarrior, etc.) without touching your system packages.

  1. Install devbox.

  2. Enter the dev shell and set up the project in one go:

    devbox shell
just setup-dev

    devbox shell activates the environment (creates a .venv and installs Python dependencies via uv automatically on first run). just setup-dev installs the package in editable mode and registers the pre-commit hooks.

  3. For subsequent sessions just re-enter the shell:

    devbox shell   # or: just shell

Common tasks via just

just is the project's task runner. Run just (no arguments) inside the dev shell to list all available recipes.

Recipe What it does
just setup-dev Full first-time setup (deps + pre-commit)
just setup-deps Re-install Python dependencies only
just setup-pre-commit (Re-)install pre-commit hooks
just shell Open a devbox shell
just check Run all pre-commit checks across the whole codebase
just test Run the test suite
just gen-completions Regenerate shell completions

Linting and formatting

The project uses ruff for linting and formatting, wired up through pre-commit. The configuration lives in pyproject.toml under [tool.ruff].

Use just check to run all checks (including ruff) across the whole codebase:

just check

All hooks also run automatically on every commit. To run only the ruff hooks:

pre-commit run ruff --all-files

Running the tests

just test

The pytest configuration lives in pyproject.toml.

Isolating test runs from your real data

Set SYNCALL_TESTENV before running a sync executable to redirect all config reads/writes to $XDG_CONFIG_HOME/test_syncall instead of the default $XDG_CONFIG_HOME/syncall. This lets you experiment without touching your live synchronization data.

Git Guidelines

  • Make sure that the branch from which you're making a Pull Request is rebased on top of the branch you're making the PR to.

  • In terms of the commit message:

    • Start the message header with a verb
    • Capitalise the first word (the verb mentioned above).
    • Format your commit messages in imperative form
    • If the pull-request is referring to a particular Side, prefix it with [side-name]

    For example...

    # ❌ don't do...
implemented feature A for google calendar
# ✅ instead do...
[gcal] Implement feature A
# ✅ if this is about a synchronization that's about two sides, join them by
# a dash...
[tw-gcal] Fix regression in Taskwarrior - Google Keep todo blocks integration.