OpenShell RFCs

Substantial changes to OpenShell should be proposed in writing before implementation begins. New features always start as a GitHub issue using the feature request template, not as an RFC pull request. RFCs drive nuanced discussions that need structured iteration, broad stakeholder input, and a durable record of the reasoning beyond what issue comments can fully capture.

An RFC provides a consistent way to collect broad feedback, build consensus, and document the decision for future contributors. An RFC is created only when maintainers decide the originating issue needs that level of design review.

Start with a GitHub issue

Before writing an RFC, you must open a GitHub issue to scope the problem, gauge interest, and get early feedback. For new features, use the feature request template. This helps:

• Validate that the problem is worth solving
• Surface potential concerns early
• Build consensus before investing in a detailed proposal
• Identify the right reviewers and stakeholders

If the ticket shows sufficient interest and maintainers decide the idea needs broad design review, they will ask for an RFC from that issue. Maintainers assign the RFC number and add the needs-rfc label in the issue before the RFC is created, preventing number clashes across branches and making pending RFC work searchable.

RFCs vs other artifacts

OpenShell has several places where design information lives. Use this guide to pick the right one:

Artifact	Purpose	When to use
GitHub issue	Track and scope a bug, feature request, or rough idea	Always start here; new features use the feature request template
Spike issue (create-spike)	Investigate implementation feasibility for a scoped change	You need to explore the codebase and produce a buildable issue for a specific component or feature
RFC	Propose a cross-cutting decision that needs broad consensus	Maintainers requested an RFC from an existing issue and assigned an RFC number
Architecture doc (architecture/)	Document how things work today	Living reference material — updated as the system evolves

The key distinction: spikes investigate whether and how something can be done; RFCs propose that we should do it and seek agreement on the approach. A spike may precede an RFC (to gather data) or follow one (to flesh out implementation details). When an RFC reaches implemented, its relevant content should be folded into the appropriate architecture/ docs so the living reference stays current.

When to use an RFC

Use an RFC when the discussion itself needs structure: multiple rounds of feedback, competing tradeoffs, broad stakeholder input, or a durable design record. If the important context would get lost across issue comments, an RFC is the right tool. The following are examples of when maintainers may ask for one after an issue is opened:

• An architectural or design decision for the platform
• Change to an API or command-line tool
• Change to an internal API or tool
• Add or change a company or team process
• A design for testing

RFCs don't only apply to technical ideas but overall project ideas and processes as well. If you have an idea to improve the way something is being done, you have the power to make your voice heard.

When NOT to use an RFC

Not everything needs an RFC. Skip the RFC process for:

• Bug fixes
• Small feature additions scoped to a single component (use a spike instead)
• Feature requests that can be resolved through the issue, spike, and pull request workflow
• Documentation changes
• Dependency updates
• Refactoring that doesn't change public interfaces

If a change doesn't require cross-team consensus, a GitHub issue or spike issue is the right vehicle.

RFC metadata and state

At the start of every RFC document, we include a brief amount of metadata in YAML front matter:

---
authors:
  - "@username"
state: draft
links:
  - https://github.com/NVIDIA/OpenShell/issues/456
  - https://github.com/NVIDIA/OpenShell/pull/123
---

We track the following metadata:

• authors: The authors (and therefore owners) of an RFC. Listed as GitHub usernames.
• state: Must be one of the states discussed below.
• links: Related PRs or issues. The first link should be the originating issue where maintainers requested the RFC and assigned its number. Add entries as the RFC progresses.
• superseded_by: (optional) For RFCs in the superseded state, the RFC number that replaces this one (e.g., 0005).

An RFC can be in one of the following states:

State	Description
draft	The RFC is being written and is not yet ready for formal review.
review	Under active discussion in a pull request.
accepted	The proposal has been accepted and is ready for implementation.
rejected	The proposal was reviewed and declined.
implemented	The idea has been entirely implemented. Changes would be infrequent.
superseded	Replaced by a newer RFC. The superseded_by field should reference the replacement.

RFC lifecycle

1. Open a GitHub issue

Start with a GitHub issue. New features must use the feature request template and include enough design context for maintainers and contributors to evaluate the idea. Do not open an RFC PR before an issue exists.

2. Get maintainer confirmation

Maintainers decide from the issue whether an RFC is necessary. If it is, they assign the RFC number in the issue before anyone creates the RFC branch or folder, and add the needs-rfc label to the originating issue so pending RFC work is searchable. Authors should use the assigned number instead of choosing one locally.

3. Create your RFC

Each RFC lives in its own folder:

rfc/NNNN-my-feature/
    README.md
    (optional: diagrams, images, supporting files)

Where NNNN is the maintainer-assigned RFC number (zero-padded to 4 digits) and my-feature is a short descriptive name. The main proposal goes in README.md so GitHub renders it when browsing the folder.

To start a new RFC, copy the template folder:

cp -r rfc/0000-template rfc/NNNN-my-feature

Fill in the metadata, include the originating issue in links, and start writing. The state should be draft while you're iterating.

4. Open a pull request

When you're ready for feedback, update the state to review and open a pull request. Add the PR link to links in the metadata. Maintainers should add the rfc label to the PR and add it to the RFC board.

The PR is where discussion happens. Anyone subscribed to the repo will get a notification and can read your RFC and provide feedback.

5. Iterate and build consensus

The comments you choose to accept are up to you as the owner of the RFC, but you should remain empathetic in how you engage. For those giving feedback, be sure that all feedback is constructive.

RFCs rarely go through this process unchanged. Make edits as new commits to the PR and leave comments explaining your changes.

6. Merge the pull request

After there has been time for folks to comment, the RFC author requests merge and a maintainer approves and merges. The state should be updated from review to accepted. If the proposal is declined, the state should be set to rejected. The timing is left to the author's discretion. As a guideline, a few business days seems reasonable, but circumstances may dictate a different timeline.

When an RFC is accepted, maintainers should update any RFC board fields that track review state.

In general, RFCs shouldn't be merged if no one else has read or commented on it. If no one is reading your RFC, it's time to explicitly ask someone to give it a read!

7. Implementation

Once an RFC has been entirely implemented, its state should be moved to implemented. This represents ideas that have been fully developed. While discussion on implemented RFCs is permitted, changes would be expected to be infrequent.

Diagrams

When an RFC needs diagrams to illustrate architecture, data flow, or component interactions, use Mermaid diagrams embedded directly in the Markdown. Mermaid renders natively on GitHub and keeps diagrams version-controlled alongside the text.

```mermaid
graph LR
    A[Client] --> B[Gateway]
    B --> C[Sandbox]
```

Prefer Mermaid over external image files whenever possible. If a diagram is too complex for Mermaid (e.g., detailed UI mockups), commit the image to the RFC's folder alongside its README.md and reference it with a relative path.

Making changes to an RFC

After your RFC has been merged, there is always opportunity to make changes. Open a pull request with the change you would like to make. If you are not the original author, be sure to @ the original authors to make sure they see and approve of the changes.

RFC postponement

Some RFCs are marked rejected when the proposal is declined or when we want neither to think about evaluating the proposal nor about implementing it until some time in the future. Rejected RFCs may be revisited when the time is right.