generated from coulomb/repo-seed
tegwick
12b5d83091
Some checks failed
ci / validate-registry (push) Has been cancelled
Implement Integration Definition validator CLI with schema and index checks, pytest suite, and CI workflow. Register open-cmis-tck and issue-core-gitea in the integration index. Closes OPEN-WP-0003 and OPEN-WP-0004.
219 lines
8.6 KiB
Markdown
219 lines
8.6 KiB
Markdown
# open-reuse Registry
|
||
|
||
Markdown-first registry for managed open-source integration assets.
|
||
|
||
## Layout
|
||
|
||
```text
|
||
registry/
|
||
├── README.md
|
||
├── integrations/ # optional local definitions (most live in consuming repos)
|
||
├── capabilities/ # federation capability index (reuse-surface)
|
||
└── indexes/
|
||
├── integrations.yaml # integration discovery index
|
||
└── capabilities.yaml # capability federation index
|
||
schemas/
|
||
└── integration.schema.yaml
|
||
templates/
|
||
└── integration-entry.template.yaml
|
||
```
|
||
|
||
- **Integration definitions** are YAML files conforming to `schemas/integration.schema.yaml`.
|
||
They usually live in the consuming repository (e.g. `integration/<id>.integration.yaml`).
|
||
- **Index** at `indexes/integrations.yaml` is the discovery surface for registered
|
||
integrations across the portfolio.
|
||
- **Template** at `templates/integration-entry.template.yaml` is the authoring
|
||
starting point for new definitions.
|
||
- **Capability index** at `indexes/capabilities.yaml` supports reuse-surface
|
||
federation; see [Capability Registry](#capability-registry) below.
|
||
|
||
## Integration lifecycle loop
|
||
|
||
open-reuse starts **after an integration has proven value**. The registry captures
|
||
the outcome of a structured loop that turns informal reuse into a managed asset.
|
||
|
||
```text
|
||
Analyze → Classify → Refactor → Maintain
|
||
```
|
||
|
||
### 1. Analyze
|
||
|
||
Understand the working integration before encoding it.
|
||
|
||
| Question | Artifact |
|
||
| -------- | -------- |
|
||
| What upstream project is reused? | `upstream.name`, `upstream.project_url` |
|
||
| What local system depends on it? | `local.system`, `owner` |
|
||
| What surfaces are actually reused? | `boundary.reused_surface`, `boundary.contracts` |
|
||
| What runtime assumptions exist? | `runtime` |
|
||
| What breaks when upstream changes? | `risks.sensitivity`, `boundary.fragility_points` |
|
||
| How is correctness proven today? | `validation.harness`, `validation.checks` |
|
||
|
||
**Output:** enough context to classify reuse mode and draw a defensible boundary.
|
||
Incomplete analysis is acceptable in `status: draft`; missing upstream or boundary
|
||
information blocks promotion to `registered`.
|
||
|
||
### 2. Classify
|
||
|
||
Assign an explicit reuse mode so risk, validation depth, and update policy can
|
||
be chosen systematically.
|
||
|
||
| Reuse mode | Typical risk | Notes |
|
||
| ---------- | ------------ | ----- |
|
||
| `dependency` / `dependency-reuse` | Low | Package, library, image, or service consumption |
|
||
| `plugin` | Low–medium | Official extension points |
|
||
| `adapter` | Medium | Upstream wrapped behind a local interface |
|
||
| `component-extraction` | High | Selected internal parts reused |
|
||
| `patch-overlay` | High | Local patches on upstream |
|
||
| `fork-continuation` | Very high | Divergent fork, upstream-aware |
|
||
| `cli-boundary` | Medium | CLI invocation as the integration seam |
|
||
|
||
Record classification in `reuse.primary_reuse_mode`, optional
|
||
`reuse.secondary_reuse_modes`, and `reuse.risk_level`.
|
||
|
||
**Output:** `reuse` block with rationale. Unclassified integrations remain
|
||
incomplete until `primary_reuse_mode` is set.
|
||
|
||
### 3. Refactor
|
||
|
||
Establish a clear, testable boundary between local systems and upstream change.
|
||
|
||
The `boundary` block documents the seam:
|
||
|
||
- **Type** — adapter, cli-boundary, plugin-boundary, schema-boundary, etc.
|
||
- **Local side** — `local_adapter`, `local_interface`, `entry_point`
|
||
- **Upstream side** — `reused_surface`, `contracts`
|
||
- **Fragility** — `fragility_points` where upstream drift hurts first
|
||
|
||
Refactoring work happens in the consuming repository. The Integration Definition
|
||
records the resulting boundary so automation and maintainers know what to protect.
|
||
|
||
**Output:** `boundary` with at least one concrete local/upstream reference.
|
||
Domain-specific keys (e.g. `markitect_adapter_id`) are allowed.
|
||
|
||
### 4. Maintain
|
||
|
||
Register the definition, assign maintainers, and connect validation to ongoing
|
||
upstream monitoring.
|
||
|
||
| Concern | Field |
|
||
| ------- | ----- |
|
||
| Registry visibility | row in `indexes/integrations.yaml` |
|
||
| Accountability | `maintenance.maintainers` |
|
||
| When humans must act | `maintenance.escalation_conditions`, `risks.escalation_triggers` |
|
||
| Proving continuity | `validation.harness` |
|
||
| Update behavior | `update_policy.default_action` |
|
||
| Lifecycle | `status` (see schema enum) |
|
||
|
||
**Output:** integration moves from `draft` → `registered` → `active` once
|
||
maintainers, validation, and index registration are in place.
|
||
|
||
### Full product lifecycle (context)
|
||
|
||
The four-step loop above is the minimum path to a registry entry. The broader
|
||
open-reuse lifecycle (see `INTENT.md`) also includes reframe, register, monitor,
|
||
auto-update, validate, and escalate. Registry format v0.1 encodes the knowledge
|
||
those later stages require.
|
||
|
||
```text
|
||
Prove Value
|
||
→ Analyze → Classify → Refactor → Create Integration Definition
|
||
→ Register in indexes/integrations.yaml
|
||
→ Monitor upstream → Validate → Update or Escalate
|
||
```
|
||
|
||
## Add a new integration (v0.1)
|
||
|
||
1. Copy `templates/integration-entry.template.yaml` to the consuming repo at
|
||
`integration/<id>.integration.yaml`.
|
||
2. Complete the **Analyze** and **Classify** sections: upstream, reuse mode, risks.
|
||
3. Complete the **Refactor** section: `boundary` with explicit local/upstream seams.
|
||
4. Complete the **Maintain** section: validation harness, maintainers, update policy.
|
||
5. Set `schema_version: open-reuse.integration.v0.1`.
|
||
6. Add a row to `registry/indexes/integrations.yaml` with `id`, `path`, `repo`,
|
||
`reuse_mode`, and `upstream` summary.
|
||
7. Run `open-reuse validate --repos-base <portfolio-root>` before setting
|
||
`status: active`.
|
||
|
||
Early adopters may use `schema_version: open-reuse.integration.v1`; the schema
|
||
accepts both. New entries should use v0.1.
|
||
|
||
## Automated validation
|
||
|
||
Primary validation path:
|
||
|
||
```bash
|
||
# Install (from repo root)
|
||
python -m pip install -e ".[dev]"
|
||
|
||
# Validate local definitions and registry index
|
||
open-reuse validate
|
||
|
||
# Validate index rows against consuming-repo definitions
|
||
open-reuse validate --repos-base /home/worsch
|
||
|
||
# Treat promotion-gate warnings as failures (CI default for strict checks)
|
||
open-reuse validate --repos-base /home/worsch --fail-on-warnings
|
||
```
|
||
|
||
CI runs `open-reuse validate --indexed-only` on every push to `main`.
|
||
|
||
## Manual validation checklist
|
||
|
||
Fallback when the CLI is unavailable.
|
||
|
||
### Required fields
|
||
|
||
- [ ] `schema_version` is `open-reuse.integration.v0.1` (or accepted `v1` draft)
|
||
- [ ] `id` matches `^[a-z][a-z0-9-]*$`
|
||
- [ ] `name`, `upstream.name`, `reuse.primary_reuse_mode` are present
|
||
- [ ] `boundary` has at least one local and one upstream reference
|
||
- [ ] `validation.harness` is a runnable command or documented CI entry point
|
||
- [ ] `maintenance` includes `maintainers` or `escalation_conditions`
|
||
|
||
### Promotion gates
|
||
|
||
| Target status | Requires |
|
||
| ------------- | -------- |
|
||
| `draft` | Core identity + upstream + reuse mode |
|
||
| `registered` | Boundary + validation harness + index row |
|
||
| `active` | Maintainers + update policy + passing validation |
|
||
|
||
### Enum checks
|
||
|
||
Reuse modes: see schema `reuseMode` enum in `schemas/integration.schema.yaml`.
|
||
Lifecycle status: `draft`, `registered`, `active`, `needs_review`, `degraded`,
|
||
`paused`, `deprecated`, `retired`.
|
||
Update actions: `ignore`, `monitor-only`, `open-issue`, `open-update-proposal`,
|
||
`open-pull-request`, `auto-merge-after-validation`, `require-maintainer-review`,
|
||
`block-update`, `escalate`.
|
||
|
||
### Index checks
|
||
|
||
- [ ] New entry appears in `indexes/integrations.yaml`
|
||
- [ ] `path` and `repo` point to the definition file in the consuming repository
|
||
- [ ] `reuse_mode` matches `reuse.primary_reuse_mode` in the definition
|
||
- [ ] `upstream.name` matches the definition
|
||
|
||
## Reference integrations
|
||
|
||
| ID | Repo | Reuse mode | Definition path |
|
||
| -- | ---- | ---------- | --------------- |
|
||
| `markitect-quarkdown` | markitect-quarkdown | adapter | `integration/quarkdown.integration.yaml` |
|
||
| `open-cmis-tck` | open-cmis-tck | adapter | `integration/opencmis-tck.integration.yaml` |
|
||
| `issue-core-gitea` | issue-core | adapter | `integration/gitea-backend.integration.yaml` |
|
||
|
||
`markitect-quarkdown` is the primary worked example for adapter + cli-boundary
|
||
reuse. `open-cmis-tck` illustrates cli-boundary orchestration of an upstream
|
||
test harness. `issue-core-gitea` illustrates a remote API backend adapter.
|
||
|
||
## Capability registry
|
||
|
||
The capability index supports reuse-surface federation for cross-repo planning.
|
||
|
||
1. Copy a capability entry template (see reuse-surface `templates/capability-entry.template.md`).
|
||
2. Add the row to `indexes/capabilities.yaml`.
|
||
3. Run `reuse-surface validate` from a checkout with the CLI installed.
|
||
4. Merge to `main` and verify publish with `reuse-surface establish --publish-check`.
|
||
|
||
Federation contract: reuse-surface `docs/RegistryFederation.md`. |