registrystack / registrystack/registry-stack

Finalize 1.0 lifecycle policies and exercise upgrade and rollback

オープン
#203 コメント 5 件 リアクション 0 件 担当者 0 名 GitHub で見る
1.0-blocker area:docs documentation triage:needs-implementation
主要言語
Rust
スター
2
フォーク
0
平均マージ
2時間 55分
マージ済み PR(30日)
130

説明

Part of the 1.0 release-readiness push (see `release/READINESS.md`).

## Context

A stable release is a promise to institutions that operate Registry Stack. The API, deprecation, security maintenance, state migration, upgrade, and rollback boundaries must be written and exercised before 1.0 rather than inferred from SemVer.

Draft policy pages already exist, but they remain draft until their promises match the implemented state and the required exercise is complete.

## Maintainer decisions

Approved 2026-07-19:

1. **Version promise:** Use one stack-wide SemVer and release line.
2. **Metrics:** Stabilize metric family names, types, label keys, and label meaning. Allow additive families and values. Exclude help text, ordering, and corrected observed values from the compatibility promise.
3. **Deprecation:** Remove a covered surface only in a later major and no earlier than six months after the deprecating release, except for an explicitly documented security removal.
4. **Security maintenance:** Roll users forward to the latest minor of the supported major. Do not promise a backport lane that does not exist.
5. **Major-line end of life:** Announce at least 90 days before the successor stable major, publish the exercised upgrade path, and support the old major until the successor is released.
6. **Persistent state:** Preserve wire, configuration, and client compatibility within a major. Provide a documented forward state path from the preceding release. Skipped releases use sequential hops unless explicitly certified.
7. **Rollback:** Require general rollback before target-version traffic admission. After target writes or credential issuance, default to fix-forward unless that release proves a safe recovery conversion.
8. **Error semantics:** Give each released error-code literal one stack-wide meaning. HTTP mapping may differ by product and operation, but changing an existing product/operation mapping is breaking.

The covered 1.0 surfaces include HTTP APIs, configuration formats, Registry Manifest schemas, registryctl's documented CLI and machine formats, signed configuration bundle format and verification semantics, released machine error codes, selected metrics, and other surfaces explicitly listed by the API stability policy.

Notary state upgrades are forward-only. An older binary must never start against a newer schema. The supported topology has one Notary authority per Relay authority.

## Implementation scope

- Reconcile and promote the lifecycle, API stability, deprecation, security-support, upgrade/rollback, backup/restore, and error pages from draft only after contradictions are removed.
- Add base-reference OpenAPI compatibility comparison for Relay and Notary.
- Add additive compatibility guards for released error codes and selected metrics.
- Consume #227 product schemas rather than creating another configuration model.
- Add a structured, redaction-safe upgrade exercise template and validator.
- Exercise upgrade and rollback against a pinned standalone Solmara release topology.
- Cover Notary PostgreSQL schema upgrade, complete database plus sensitive-key backup and restore, forward-only compatibility, release-specific rollback restore sets, and anti-rollback startup behavior.
- Record candidate-neutral preparation separately from exact frozen-candidate evidence.
- Exercise registry-backed issuance as part of the frozen-candidate journey.
- Treat any suspected vulnerability through `SECURITY.md`, not this public issue.

## Acceptance

- [ ] All policy pages reflect the approved decisions, have no unresolved contradictions, and are reviewed before promotion from draft.
- [ ] Relay and Notary OpenAPI compatibility comparison runs against the base reference.
- [ ] Released error codes and selected metrics have automated additive-compatibility guards.
- [ ] The structured upgrade exercise template and validator are committed and redaction-safe.
- [ ] Upgrade, complete backup, restore, rollback boundary, and anti-rollback behavior are exercised against the exact independently verified candidate and pinned standalone Solmara topology.
- [ ] The exercise proves one Notary authority per Relay authority and registry-backed issuance.
- [ ] Evidence is rerun if any stable candidate artifact changes.

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

release/READINESS.md と、既存のドラフトライフサイクル、API の安定性、非推奨化、セキュリティサポート、アップグレード/ロールバック、バックアップ/リストア、エラーページから始めます。実装範囲を受け入れチェックリストに対応付け、その後、既存の Relay、Notary、schema、exercise のエントリポイントを調べます。完了とは、ポリシーに矛盾がなく昇格され、互換性ガードとレダクションセーフな validator が存在し、固定された候補のアップグレード、バックアップ、リストア、ロールバック、アンチロールバックの証跡が記録されていることを意味します。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
openapi, postgresql, rust
領域
api, databases, documentation, release, security, testing
issue の種類
機能追加
難易度
5/5
見積もり時間
1週間以上
活発さ
静か
明瞭さ
おおむね明確
初心者へのやさしさ
25/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。