Skip to content

docs(readme): add roadmap and RFC issue guidance #1284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
drew wants to merge 1 commit into
base: main
Choose a base branch
from
+8 −7
Open

docs(readme): add roadmap and RFC issue guidance #1284

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,6 +234,7 @@ All implementation work is human-gated — agents propose plans, humans approve,
- [Quickstart](https://docs.nvidia.com/openshell/latest/get-started/quickstart) — detailed install and first sandbox walkthrough
- [GitHub Sandbox Tutorial](https://docs.nvidia.com/openshell/latest/tutorials/github-sandbox) — end-to-end scoped GitHub repo access
- [Architecture](https://github.com/NVIDIA/OpenShell/tree/main/architecture) — detailed architecture docs and design decisions
- [Roadmap](https://github.com/orgs/NVIDIA/projects/233) — planned work and project priorities
- [Support Matrix](https://docs.nvidia.com/openshell/latest/reference/support-matrix) — platforms, versions, and kernel requirements
- [Brev Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3Ap3tL55zq4a8kew1AuW0FpSLsg) — try OpenShell on cloud compute without local setup
- [Agent Instructions](AGENTS.md) — system prompt and workflow documentation for agent contributors
Expand Down
2 changes: 1 addition & 1 deletion rfc/0000-template/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ authors:
- "@your-github-username"
state: draft
links:
- (related PRs, discussions, or issues)
- (related PRs or issues)
---

# RFC NNNN - Your Title Here
Expand Down
12 changes: 6 additions & 6 deletions rfc/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,24 +2,24 @@

Substantial changes to OpenShell should be proposed in writing before implementation begins. An RFC provides a consistent way to propose an idea, collect feedback from the community, build consensus, and document the decision for future contributors. Not every change needs an RFC — bug fixes, small features, and routine maintenance go through normal pull requests. RFCs are for the changes that are cross-cutting, potentially controversial, or significant enough that stakeholders should weigh in before code is written.

## Start with a GitHub Discussion
## Start with a GitHub issue

Before writing an RFC, consider opening a [GitHub Discussion](https://github.com/NVIDIA/OpenShell/discussions) to gauge interest and get early feedback. This helps:
Before writing an RFC, consider opening a [GitHub issue](https://github.com/NVIDIA/OpenShell/issues/new/choose) to scope the problem, gauge interest, and get early feedback. 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 discussion shows sufficient interest and the idea has merit, then it's time to write an RFC to detail the plan and technical approach.
If the ticket shows sufficient interest and the idea has merit, then it's time to write an RFC to detail the plan and technical approach.

## 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 Discussion** | Gauge interest in a rough idea | You have a thought but aren't sure it's worth a proposal yet |
| **GitHub issue** | Track and scope a rough idea | You have a thought but aren't sure it's worth a proposal yet |
| **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 | Architectural changes, API contracts, process changes, or anything that spans multiple components or teams |
| **Architecture doc** (`architecture/`) | Document how things work today | Living reference material — updated as the system evolves |
Expand Down Expand Up @@ -61,15 +61,15 @@ authors:
state: draft
links:
- https://github.com/NVIDIA/OpenShell/pull/123
- https://github.com/NVIDIA/OpenShell/discussions/456
- https://github.com/NVIDIA/OpenShell/issues/456
---
```

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, discussions, or issues. Add entries as the RFC progresses.
- **links**: Related PRs or issues. 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:
Expand Down
Loading