RFC: (v0)¶
- RFC status: Draft | Under review | Accepted | Rejected | Superseded
- Delivery maturity: Proposal | Experiment | Partial | Implemented | Promoted
- Authors / owners:
- Created: YYYY-MM-DD
- Last normative revision: YYYY-MM-DD
- Implementation baseline:
<commit>or not applicable - Related contracts:
- Language mirror: 中文版
Document map and maintenance contract¶
State which sections are normative, which are current implementation facts,
and which are historical evidence. Use this default. Every new RFC must ship an
English document and a <same-basename>.zh-CN.md semantic mirror; a language
link is required in both documents. Keep the two versions synchronized when
normative sections change:
- Sections 1-10 are the durable design and acceptance contract.
- Section 11 is the normative delivery plan.
- Section 12 contains unresolved decisions; proposed answers are not approval.
- Appendices contain the non-normative execution ledger, decision log, evidence registry, rejected alternatives, and incident lessons.
RFC maturity and delivery maturity are independent. Dated progress entries do
not amend normative sections. If an appendix becomes hard to review, move it
without loss into a companion <rfc-name>-execution.md and link it here.
1. Decision summary¶
Lead with the smallest set of decisions a maintainer must understand. State:
- what becomes authoritative or changes behavior;
- what remains unchanged;
- the default and opt-in boundary;
- the principal safety or compatibility constraint;
- what this RFC still does not approve.
2. Problem and motivation¶
Describe the user/operator failure, not only the implementation gap. Include a concrete example and explain why the current owner cannot solve it locally.
Invariants¶
List properties that every implementation must preserve. Prefer observable semantics over mechanism names.
3. Scope and non-goals¶
In scope¶
Non-goals¶
4. Current-system contract¶
Record the audited current behavior and its owners. Distinguish facts on the named implementation baseline from proposed behavior. Link stable protocol or code ownership surfaces; do not paste execution logs into this section.
5. Proposed architecture¶
Ownership and authority¶
Name the single decision owner, storage/provider boundary, identities, transactions, and forbidden alternate authorities.
State model and schema¶
Define canonical records, version manifests, required/optional fields, explicit clear/delete semantics, ordering, and serialization. Default to preserving legally stored fields. Any reduction must enumerate affected fields, producer / reader / writer research, historical and external compatibility, migration, rollback, and semantic-equivalence evidence, with explicit maintainer approval.
Command or event lifecycle¶
Describe legal transitions, idempotency identity, preconditions, receipts, replay, ambiguity reconciliation, and fail-closed behavior.
Provider or extension contract¶
Keep logical semantics provider-neutral. Put provider-specific storage layouts, limits, authentication, and operational details in named profiles.
6. Alternatives and design choices¶
Compare viable alternatives against the invariants. Keep the final choice and its trade-off in the normative body; retain superseded detail in Appendix D.
7. Safety, privacy, and compatibility¶
Cover as applicable:
- default-off and feature-off parity;
- authorization, tenancy, and credential boundaries;
- public/private data boundaries;
- legacy readers/writers and downgrade behavior;
- partial rollout, mixed versions, and split-brain prevention;
- capacity, availability, and fail-closed/fail-open choices.
8. Migration and rollback¶
Define admission, preflight, quiescence, cutover, readback, rollback, and the point after which rollback requires export or migration. Every destructive or irreversible step needs an explicit gate and recovery path.
9. Validation and acceptance¶
Express each claim as a reproducible acceptance row:
| Claim | Test or evidence | Required result | Boundary / exclusions |
|---|---|---|---|
Separate deterministic conformance, live qualification, performance evidence, and production promotion. An unverified or skipped row is not green.
10. Operational contract¶
Describe observability, typed failures, capacity limits, backup/recovery, upgrade/downgrade, on-call or operator actions, and user-visible status. Omit this section only when the RFC cannot affect a running system, and say why.
11. Normative delivery plan¶
Use cohesive milestones with explicit entry and exit gates. A milestone may ship while the RFC remains Draft.
| Milestone | Shipped behavior | Entry gate | Exit evidence | Rollback |
|---|---|---|---|---|
| M0 |
Keep progress percentages and dated status reports out of this section.
12. Open decisions¶
Number each unresolved decision. For each, name the decision owner, options, recommendation, evidence needed, and deadline or dependent milestone. A recommendation remains non-authoritative until the decision log records approval.
Appendix A: Execution ledger (non-normative)¶
Append dated entries; do not rewrite history to resemble the current plan. Each entry states the exact implementation baseline and claim boundary.
YYYY-MM-DD — ¶
- Baseline:
<commit>/ PR - Delivered:
- Evidence:
- Known gaps:
- Effect on normative design: none |
Appendix B: Decision log¶
| Date | Decision | Owner / approval | Alternatives | Normative sections changed |
|---|---|---|---|---|
| YYYY-MM-DD |
Do not infer approval from implementation progress, silence, or a proposed answer. Schema/field removal entries name every removed field explicitly.
Appendix C: Evidence registry¶
| Evidence id | Claim | Baseline / environment | Artifact or command | Result | Privacy / validity boundary |
|---|---|---|---|---|---|
| E1 | pass/fail/unverified |
Never commit credentials, private links, raw transcripts, local paths, or unredacted production evidence.
Appendix D: Rejected or superseded alternatives¶
Preserve enough detail to prevent the same dead end from being rediscovered. State why it failed an invariant and what evidence could reopen the decision.
Appendix E: Incident and review lessons¶
Record generalized, public-safe lessons that changed an invariant, acceptance row, or migration rule. Operational timelines and private incident material belong outside the public RFC.