Skip to content

spec: migrate RFCs to spec/rfcs/ with template + lifecycle doc (closes #66)#69

Merged
proofmancer merged 1 commit into
mainfrom
spec/rfc-process
May 25, 2026
Merged

spec: migrate RFCs to spec/rfcs/ with template + lifecycle doc (closes #66)#69
proofmancer merged 1 commit into
mainfrom
spec/rfc-process

Conversation

@proofmancer
Copy link
Copy Markdown
Member

Closes #66.

Promotes the five open RFCs from "GitHub issues with the design label" to structured markdown files with frontmatter, in a dedicated directory with a documented lifecycle. Standard pattern for any language project that wants to be open to community contributions; this matches what Rust, Ethereum, Cosmos, and Bitcoin all do.

What landed

Directory + process docs

  • `spec/rfcs/README.md`: explains what gets an RFC, how to open one, the lifecycle (draft / accepted / implemented / superseded / rejected), the frontmatter format, and what an RFC is not
  • `spec/rfcs/0000-template.md`: copy-this-for-new-RFCs template with sections for summary, motivation, design, alternatives, drawbacks, open questions, reversibility, related work, implementation roadmap

Migrated RFCs

Five proposals lifted from issue bodies into structured files:

File Tracking
`spec/rfcs/0001-memory-model.md` #42
`spec/rfcs/0002-extern-host-abi.md` #55
`spec/rfcs/0003-project-metadata.md` #45
`spec/rfcs/0004-cross-engine-state.md` #46
`spec/rfcs/0005-third-party-protocols.md` #65

Each gets YAML frontmatter:

```yaml

rfc: 0001
title: "Memory model for Cleave (ownership, GC, escape hatches)"
status: draft
authors: ["Cleave Labs"]
tracking: #42
created: 2026-05-23

```

The body text is unchanged from the issue. Substantive edits happen via PRs against the file going forward.

Cross-linking

Each tracking issue gets a comment pointing at its new RFC file. Discussion continues on the issue; the file is the source of truth for proposal text.

Spec index

`spec/README.md` table updated:

  • Adds `spec/rfcs/` entry pointing at the RFC index
  • Marks module bodies, type system, ABI as stable now (was planned); they shipped in v0.3
  • Marks the standard-library reference as planned (v0.5+) (was planned (v0.2))

Why now

Five RFCs is the inflection point. Below that, GitHub issues are fine. Above, structure matters:

  • A markdown file has a stable URL anyone can cite
  • Frontmatter gives at-a-glance state
  • A template makes RFCs consistent and easier to write
  • The process docs onboard external contributors
  • Numbering establishes a citation surface

What this PR does NOT do

  • No automation: no `make rfc` script, no lifecycle-state bot, no RFC-to-implementation linker. Manual for now; volume does not justify tooling.
  • No new RFCs: every RFC in this PR existed before, just as issue text. Six RFCs (0000 template + 0001-0005) is the new baseline; the next one to be filed is 0006.
  • Does not move `spec/protocols/*.md`: those are stable specs for shipped interfaces (consensus, gas, state, da, effects RFCs). RFCs and stable specs are different artifacts: an RFC is a proposal; a spec is the stable contract once accepted and implemented. Future RFCs about protocols start in `spec/rfcs/`, graduate to `spec/protocols/` once shipped.

What unblocks next

@proofmancer proofmancer merged commit 59fdff8 into main May 25, 2026
2 checks passed
@proofmancer proofmancer deleted the spec/rfc-process branch May 25, 2026 16:41
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.

Process: migrate RFCs to spec/rfcs/ with template + numbering + lifecycle doc

1 participant