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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions