RFC Template¶

Use this template for RFCs in docs/RFCs/. Keep the RFC focused: one coherent proposal, with clear motivation, semantics, and implementation strategy.

Title¶

RFC NNN: \<short descriptive title>

Status: Draft
Created: \<YYYY-MM-DD>
Author(s): \<name (@handle)>
Related: \<RFC links, if any>
Issue: \<link to issue>
RFC PR: \<link to PR>
Written against: \<version>
Shipped in: —

Summary¶

One paragraph describing what this RFC proposes.

Motivation¶

Explain the problem and why it matters:

What’s painful/confusing today?
Who benefits?
Why is this better than the status quo?

Guide-level explanation (how users think about it)¶

Explain the feature as a user would understand it. Include examples.

# Example code

Reference-level explanation (precise rules)¶

Define exact semantics, typing rules, and edge cases.

Syntax changes (grammar-ish description, if needed)
Type checking rules
Runtime behavior
Errors / diagnostics

Design details¶

Syntax¶

Describe new/changed syntax.

Semantics¶

Describe behavior precisely.

Interaction with existing features¶

How this composes with:

async/await
traits/derives
imports/modules
error handling (Result/Option)
Rust interop

Compatibility / migration¶

Is this breaking?
If yes, provide a migration strategy and examples.

Alternatives considered¶

List plausible alternatives and why they’re worse.

Drawbacks¶

What does this cost (complexity, performance, mental model)?

Layers affected¶

Describe which compiler and tooling layers this RFC impacts, and what each layer must do differently. Use normative language (must, must not, should). Do not list task steps or reference specific internal files or struct names — those belong in the implementation issue.

Parser — …
Typechecker — …
Lowering / IR emission — …
Stdlib — …
CLI / tooling — …
LSP / formatter — …

Inspectability and tooling surface¶

Name how users, tools, CI, editors, and agents can see what this feature did. Keep this section short, but be concrete.

Artifact or metadata: What manifest, checked metadata, report, generated output, runtime registry, or other artifact exposes this behavior?
Inspection command: What command or tooling path inspects it? If an existing command already covers it, name that command instead of inventing a new one.
Diagnostics: What diagnostic is emitted when the feature is invalid, ambiguous, unsupported, or unsafe?
Provenance: Which source span, declaration, package, dependency, or generated-output breadcrumb anchors the behavior?
Not implicit: Which behavior is intentionally not hidden magic, inferred side effect, or undocumented generated-Rust detail?

Tiny clarifications may answer “covered by existing surface X.” Larger language, stdlib, metadata, or tooling features should name a real surface that can be tested without reading compiler internals.

Unresolved questions¶

Open questions to decide before implementation lands.