Skip to content

docs: explain Contract-Driven Development for component interfaces - #45

Closed
mnriem wants to merge 1 commit into
mainfrom
mnriem-contract-driven-development
Closed

mnriem wants to merge 1 commit into
mainfrom
mnriem-contract-driven-development

Conversation

@mnriem

@mnriem mnriem commented Sep 17, 2026

Copy link
Copy Markdown
Owner

Description

Fixes github#4609.

Add a self-contained Contract-Driven Development guide and link it from the SDD overview, monorepo guide, and documentation navigation.

The guide starts with interacting components and their externally observable obligations, not repository coordination. It covers defining missing contracts, one authoritative owner with consumer participation, direct references within a repository, pinned artifacts or synchronized copies across repositories, verification on both sides, and deliberate compatible evolution.

Includes standalone website/orders/inventory and control-plane/data-plane/integration-tests examples. No new CLI commands, core template changes, mandatory umbrella repository, dependency resolver, or release orchestrator.

Context and credit

Testing

  • Tested locally with uv run specify --help
  • Ran existing tests with uv sync && uv run pytest
  • Tested with a sample project (if applicable)

The CLI and sample-project checks above are not applicable to this documentation-only change; the Python suite was not run.

Passed:

  • npx --no-install markdownlint-cli2 docs/guides/contract-driven-development.md docs/guides/monorepo.md docs/concepts/sdd.md
  • git diff --check upstream/main
  • Local relative-link and anchor checks, navigation entry uniqueness, and DocFX content inclusion.
  • Review against the existing plan/tasks command behavior and the issue scope, including the user's subsequent requirement that the site be self-contained.

The diff against upstream contains only four documentation files. A full DocFX build and rendered-site visual inspection were not performed.

AI Disclosure

  • I did not use AI assistance for this contribution
  • I did use AI assistance (fill in the disclosure below)

AI disclosure: GitHub Copilot using GPT-6 Astra (model ID: gpt-6-astra) drafted, revised, reviewed, checked, committed, and submitted this documentation on behalf of @mnriem in an interactive session. The user supplied the architectural direction and requested refinements; the documentation edits and checks were performed autonomously by the agent, without a claim of line-by-line human review. Reasoning-effort configuration is not exposed to the agent. AI involvement is documentation and PR-text generation only, not production code changes.

…ithub#4609)

Document authoritative ownership, versioned sharing, bilateral verification, and compatible evolution across component boundaries. Add self-contained checkout and control-plane examples and link the guide from the documentation site.

Assisted-by: GitHub Copilot (model: gpt-6-astra, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@mnriem mnriem closed this Sep 17, 2026
@mnriem
mnriem deleted the mnriem-contract-driven-development branch September 21, 2026 23:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document Contract-Driven Development for component interfaces

1 participant