Skip to content

Contributing

This page covers everything you need to contribute to weevr -- from environment setup to submitting a pull request. It extends the root CONTRIBUTING.md with documentation-specific workflows.

Prerequisites

  • Python 3.11 -- weevr targets Fabric Runtime 1.3, which ships Python 3.11. The version is pinned via .python-version.
  • uv -- Used for dependency management, virtual environment creation, and running all project commands.
  • Git -- Configured with your name and email for commit sign-off.

Initial setup

Clone the repository and install all development dependencies:

git clone https://github.com/ardent-data/weevr.git
cd weevr
uv python install 3.11
uv sync --dev

This creates a .venv directory (ignored by git) with all runtime and dev dependencies including Ruff, Pyright, pytest, MkDocs Material, and mkdocstrings.

Running checks locally

Before opening a pull request, run all four checks and confirm they pass.

Linting

uv run ruff check .

Ruff enforces rules from the E, F, I, UP, B, SIM, and D (Google-style docstrings) rule sets. Line length is 100 characters.

Formatting

uv run ruff format .

Ruff formats with double quotes, 4-space indentation, and a 100-character line limit. Run this before committing to avoid CI failures.

Type checking

uv run pyright .

Pyright runs in standard mode against Python 3.11. All public functions must have type annotations.

Tests

uv run pytest

Tests live in tests/weevr/ and mirror the src/weevr/ structure. Tests marked with @pytest.mark.spark are excluded by default (they require PySpark and Delta Lake). Run them explicitly with:

uv run pytest -m spark

For verbose output and coverage:

uv run pytest -v --cov

Branching model

Create feature branches from main. Never commit directly to main.

Pattern Purpose
feat/<topic> New feature
fix/<topic> Bug fix
chore/<topic> Maintenance or tooling
docs/<topic> Documentation only
ci/<topic> CI/CD changes

Keep branches short-lived and focused on a single logical change.

Commit sign-off (DCO)

Every commit must include a Signed-off-by line. This is enforced by a GitHub App and is a required status check.

git commit -s -m "feat(config): add variable interpolation"

To automatically sign off all commits:

git config --global format.signoff true

If you forget the sign-off, amend the commit:

git commit --amend --signoff
git push --force-with-lease

Pull request guidelines

Scope

  • One logical change per PR
  • Do not mix unrelated concerns (e.g., a new feature with a CI change)

PR title format

PR titles must follow Conventional Commits syntax. This project uses Release Please for versioning, and PR titles become changelog entries.

feat(engine): add parallel thread execution
fix(config): resolve variable substitution in nested maps
chore(ci): pin ruff version in workflow
docs(guides): add observability guide

Always include the component scope in parentheses.

Breaking changes

Indicate breaking changes with ! after the type:

feat(model)!: rename thread execution fields

Or include a BREAKING CHANGE: section in the PR description.

Merge strategy

Use Squash and merge so the PR title becomes the single commit message on main.

PR template

The repository includes a pull request template at .github/pull_request_template.md. Fill in all sections: Summary, Why, What changed, How to test, Release/Versioning, and Notes.

Code style

Setting Value
Line length 100 characters
Quotes Double
Indentation 4 spaces
Import order isort via Ruff (weevr as first-party)
Docstrings Google style, required for public APIs
Line endings LF (Unix)
Trailing space Remove
Final newline Required

Documentation workflow

The documentation site is built with MkDocs Material and API references are generated by mkdocstrings.

Serving docs locally

Start a local development server with hot reload:

uv run mkdocs serve

This serves the site at http://127.0.0.1:8000 and automatically rebuilds when you save changes to any Markdown file or mkdocs.yml.

Building docs

Run a strict build to catch warnings and broken links:

uv run mkdocs build --strict

The --strict flag treats warnings as errors. CI runs this same command, so fix any warnings locally before pushing.

Adding a new documentation page

  1. Create a new .md file in the appropriate docs/ subdirectory.
  2. Add the page to the nav section in mkdocs.yml.
  3. Verify it renders correctly with uv run mkdocs serve.

The nav structure in mkdocs.yml controls the sidebar and top-level tabs. Pages not listed in nav are still accessible by URL but will not appear in navigation.

Documentation structure

docs/
  index.md                          -- Home page
  tutorials/                        -- Step-by-step learning guides
  how-to/                           -- Task-oriented recipes
  reference/                        -- YAML schema, API docs, config keys
    yaml-schema/
    api/
  concepts/                         -- Architecture and design explanations
  guides/                           -- Operational guides (Fabric, observability)
  faq.md                            -- Frequently asked questions
  contributing.md                   -- This page
  release-notes/                    -- Per-version release notes

This follows the Diataxis documentation framework: tutorials, how-to guides, reference, and explanation.

Writing conventions

  • Headings -- Use # for the page title (one per page), ## for sections, ### for subsections.

  • Admonitions -- Use MkDocs Material admonitions for callouts:

    !!! note "Title"

    Admonition body text.

!!! tip

    Tip without a custom title.

!!! warning

    Warning about a common pitfall.

  • Code blocks -- Always specify the language for syntax highlighting (python, yaml, bash, json, etc.).

  • Line length -- Keep lines under 100 characters where practical. Long URLs and code blocks are exceptions.
  • Links -- Use relative paths for internal links (../concepts/thread-weave-loom.md). Use absolute URLs only for external sites.

Versioned documentation

The project uses mike for doc versioning. Version management is handled by the release workflow -- you do not need to interact with mike during normal development. Just write docs against the current version.

API documentation

API reference pages in docs/reference/api/ use mkdocstrings to render docstrings from source code:

::: weevr.context.Context

When you add or modify a public class or function, ensure it has a Google-style docstring. mkdocstrings will automatically pick up the changes.

CI checks

All pull requests run the following checks in GitHub Actions:

Check Command
Lint uv run ruff check .
Format uv run ruff format --check .
Type check uv run pyright .
Tests uv run pytest
Docstring coverage uv run interrogate
DCO sign-off GitHub App check

All checks must pass before a PR can be merged.

Project structure

src/weevr/                -- Library source (src layout)
tests/weevr/              -- Tests (mirrors src structure)
docs/                     -- Documentation source (MkDocs)
.github/                  -- Workflows, templates, CODEOWNERS
mkdocs.yml               -- MkDocs configuration
pyproject.toml            -- Project metadata and tool configs

Test files mirror the source layout. If you add src/weevr/config/macros.py, the corresponding test file goes in tests/weevr/config/test_macros.py.

Getting help

  • Open an issue for bug reports or feature requests.
  • Check the FAQ for common questions.
  • Review existing PRs for examples of the expected contribution style.