Skip to content

Docs: packaging guide for third-party compliance implementations #232

@mlieberman85

Description

@mlieberman85

Goal

Make it straightforward for an external team to package their own darnit implementation plugin (their org's policy, a regulator's framework, an internal baseline) and publish it so darnit discovers it via entry points.

Scope

A new doc, likely docs/packaging-plugins.md, covering:

  • Minimum pyproject.toml for an implementation: entry-point declaration, dependency on darnit, Python version pins.
  • Where to put TOML control definitions and how the framework discovers them.
  • How register() and the ComplianceImplementation protocol fit together (cross-reference to CLAUDE.md and framework-design/spec.md).
  • Versioning: how to declare spec_version and what changes warrant a bump.
  • Signing: Sigstore-signed wheels and the [plugins] trust config in .baseline.toml.
  • Testing: how to use darnit-testchecks patterns for plugin tests.
  • Distribution: PyPI, private indexes, git installs.

Why now

The framework already supports third-party plugins (darnit.implementations entry point), and we've internally built darnit-baseline, darnit-gittuf, etc. against the protocol. The path is real but undocumented externally — someone trying it today has to read the source.

Acceptance

  • docs/packaging-plugins.md lands.
  • A worked example: tiny "hello-world" implementation that registers one control and is installable from a separate repo.
  • Cross-linked from README and from the framework-design spec.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions