Skip to content

Contributing

Contributing illustration

Thanks for improving MCP Zen of Languages. Whether you're fixing a bug, adding a detector, or bringing support for a new language — this section gives you the context to contribute effectively.

Local development workflow

Setup

uv sync --all-groups --all-extras

Run Checks

uv run pytest -xvs
uv run ty check
uv run ruff check
uv run zensical build -f mkdocs.yml
uv run python scripts/check_docs_contrast.py --build --mode check

Pre-commit

pre-commit install
pre-commit run --all-files

Notes

  • Use Python 3.12+ typing (str | None, list[str]).
  • Pydantic v2 only (use ConfigDict, avoid class Config).
  • Rule metrics must match detector config field names.
  • Language modules must include __init__.py, analyzer.py, detectors.py, and rules.py.
  • Follow the rendering conventions in docs/contributing/rendering-style-guide.md for all terminal UX changes.

  • Development

    Local setup, quality gates, test commands, and CI expectations.

    Development

  • Add a Language

    Define zen principles, create an analyzer, wire detectors — step by step.

    Adding a Language

  • Add a Detector

    Implement a violation detector with the Strategy pattern and register it.

    Adding a Detector

  • Architecture

    How Template Method, Strategy, Pipeline, and Factory patterns connect.

    Architecture

  • Content Quality Guide

    Hybrid docs-from-code ownership, editorial standards, and release checks.

    Content Quality Guide

  • Rendering Guide

    Rich/Typer output conventions and terminal UX patterns.

    Rendering Style Guide

  • Zensical Migration

    Updated docs engine/build workflow and theme migration notes.

    Zensical Migration

Before opening a PR

Quality gates

Run these locally before pushing:

uv run ruff check                # Lint
uv run pytest                     # Tests
uvx pre-commit run --all-files    # Pre-commit hooks

Include a regression test and note the root cause in your PR description.

Add documentation, usage examples, and update the rule/detector mapping if applicable.

Follow the Adding a Detector guide. Include at least one positive and one negative test case.

Keep PRs focused

Scope each PR to one detector or one language. Reviewers can validate behavior and docs together when changes are contained.

See Also

  • Zensical Migration — Theme migration and docs build workflow updates.
  • User Guide — End-user documentation surfaces impacted by contributor changes.
  • API Reference — Generated API docs from docstrings.