Contributing¶

1. Branch from main and open a pull request. One change per pull request; CI must be green before it is merged.

2. Before pushing, run the same checks CI runs:

   uv run ruff check src tests scripts && uv run ruff format --check src tests scripts
   uv run mypy --strict src
   uv run pytest
   uv run python scripts/record_fixtures.py check
   

   If the change touches upstream behaviour, also run the live tests with a key (see Testing). 3. Never commit .env, a key, an edi-token, or a fixture that did not come from scripts/record_fixtures.py record.

Design and research records¶

• DESIGN.md keeps the decision register. Each decision has a D-number (D1 hybrid backend, D2 bad keys, D4 credential form, D9 identifiers, …) with the question, the decision and the reason. Changing behaviour that a decision covers means updating that row in the same pull request; code comments cite the D-number.
• RESEARCH.md records verified EDI, DataONE and MCP facts with the date each was checked. PASTA and DataONE change without notice, so a new upstream fact goes in with its date, and a fact that stopped being true is corrected rather than deleted silently.
• CLAUDE.md and the code map summarise both for coding agents; keep them in step.

Two change logs¶

• CHANGELOG.md (repository root) is the package release log, in the Keep a Changelog format¹. Add user-visible changes under [Unreleased].
• docs/log.md is the documentation bundle's log. Every docs change adds a dated ## YYYY-MM-DD entry naming the pages created or updated.

Documentation¶

The docs/ tree is an Open Knowledge Format (OKF v0.2)³ bundle built with Zensical. Content pages carry YAML frontmatter (title, description, type, tags, generated, sources, status); section index.md files carry none. After changing docs or tools:

uv run python scripts/gen_tools_reference.py    # when a tool changed
uv run python scripts/gen_config_reference.py   # when a setting changed
uv run python scripts/gen_llms_txt.py           # always: docs/llms.txt, docs/llms-full.txt
uv run python scripts/okf_validate.py docs
uv run zensical build --clean --strict

Commit the generated files; the docs workflow fails when they drift from their sources. Pages may only state what the code on main does; tools that are not merged yet belong on the Roadmap.

Versioning¶

edi-mcp follows Semantic Versioning². The version lives in src/edi_mcp/__init__.py. The first release, v0.1.0, and its release workflow are planned for build step 7.