Skip to content

feat(spec): add providers repository split specification#474

Open
marcusburghardt wants to merge 2 commits intocomplytime:mainfrom
marcusburghardt:004-providers-repository-split
Open

feat(spec): add providers repository split specification#474
marcusburghardt wants to merge 2 commits intocomplytime:mainfrom
marcusburghardt:004-providers-repository-split

Conversation

@marcusburghardt
Copy link
Copy Markdown
Contributor

@marcusburghardt marcusburghardt commented Apr 15, 2026

Summary

Add specification 004 for migrating the OpenSCAP and AMPEL provider implementations out of the complyctl repository and into the standalone complytime-providers repository.

The spec defines the full scope of the migration:

  • Provider relocation: cmd/openscap-plugin/ and cmd/ampel-plugin/ move to complytime-providers as a monorepo with a single root go.mod.
  • Terminology rename: All uses of "plugin" referring to the extensibility mechanism are replaced with "provider" across Go identifiers, CLI output, documentation, CI workflows, and the Makefile — with explicit carve-outs for the hashicorp/go-plugin library name and the proto package (complyctl.plugin.v1, deferred to a future major version).
  • SDK rename: pkg/plugin/ is renamed to pkg/provider/; all internal import paths updated.
  • CI updates: ci_compliance.yml is updated to download the complyctl-provider-ampel binary from complytime-providers release artifacts instead of building it from source.
  • Development sequencing: complytime-providers may use a temporary replace directive during development; it must be replaced with a published versioned reference before merging.

RPM spec and testing-farm / Packit configuration updates are explicitly out of scope and will be addressed in a follow-up specification.

Related Issues

Review Hints

  • This PR contains only the specification (specs/004-providers-repository-split/spec.md) and its quality checklist (checklists/requirements.md). No source code changes are included.

  • Risks to consider when reviewing:

    • The pkg/plugin/pkg/provider/ rename changes the published Go import path for the provider SDK. Any external consumer importing github.com/complytime/complyctl/pkg/plugin will break — this must be coordinated with a tagged complyctl release that providers consume via a versioned require statement.
    • The handshake wire values ("COMPLYCTL_PLUGIN" magic cookie and UUID) are preserved byte-for-byte. Only Go identifier names change. Verify this distinction is clearly understood before implementation begins, as getting it wrong silently breaks all provider connections at runtime.
    • The ci_compliance.yml daily workflow has a new hard dependency on complytime-providers publishing release artifacts. If complytime-providers has no release yet when the complyctl CI is updated, the daily compliance check will fail. The sequencing assumption (providers repo publishes a release first) should be validated before implementation.
  • Improvements unlocked after migration:

    • Core complyctl CI runs become faster and cheaper — no more building or testing provider source on every core PR.
    • Provider authors gain a dedicated, focused repository with its own CI, issues, and release cadence, removing the need to navigate core complyctl internals.
    • New providers can be added to complytime-providers without any changes to the complyctl repository, eliminating cross-repo PR dependencies for provider lifecycle events.
    • The complytime-providers monorepo layout makes it trivial to add a third provider in the future — just a new cmd/<name>/ directory under the existing go.mod.
  • Flexibility for follow-up changes:

    • The proto package rename (complyctl.plugin.v1complyctl.provider.v1) is explicitly deferred. The spec documents the rationale (wire compatibility) and leaves a clean decision record for a future major version bump.
    • RPM and testing-farm configuration are deferred to a separate spec, keeping this change atomic and reviewable on its own merits.
    • The monorepo layout in complytime-providers does not preclude splitting providers into separate modules later — the single go.mod is a starting point, not a permanent constraint.

Add spec 004 for extracting the OpenSCAP and AMPEL providers from the
complyctl repository into the standalone complytime-providers repository.
The spec covers the full scope of the migration including: provider source
code relocation, terminology rename from 'plugin' to 'provider' across
all complyctl surfaces, complytime-providers monorepo layout (single
go.mod), CI workflow updates (ci_compliance.yml to download provider
binary from complytime-providers releases), and the pkg/plugin →
pkg/provider SDK directory rename.

RPM spec and testing-farm configuration updates are explicitly deferred
to a follow-up specification.

Assisted-by: OpenCode (claude-sonnet-4-6@default)
Signed-off-by: Marcus Burghardt <[email protected]>
@marcusburghardt marcusburghardt requested a review from a team as a code owner April 15, 2026 09:32
Comment thread specs/004-providers-repository-split/spec.md
jpower432
jpower432 previously approved these changes Apr 16, 2026
Copy link
Copy Markdown
Member

@jpower432 jpower432 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. Left two nits.

Comment thread specs/004-providers-repository-split/spec.md Outdated
- Downgrade handshake constant identifier rename from MUST to SHOULD in
  FR-013 and the related Assumptions entry; the go-plugin framework does
  not require identifier names to follow any convention, so renaming them
  is a stylistic preference with no functional impact, left to the
  implementer's discretion.
- Remove local filesystem path from the Dependencies section; the path
  was developer-machine-specific and irrelevant to other contributors.

Assisted-by: OpenCode (claude-sonnet-4-6@default)
Signed-off-by: Marcus Burghardt <[email protected]>
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.

2 participants