From caf7ddb743f1ef28cbffb9973e27bded057b7a0a Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Fri, 8 May 2026 17:36:45 -0700 Subject: [PATCH] docs(readme): add roadmap and RFC issue guidance Signed-off-by: Drew Newberry --- README.md | 1 + rfc/0000-template/README.md | 2 +- rfc/README.md | 12 ++++++------ 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 02447e421..14913b995 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/rfc/0000-template/README.md b/rfc/0000-template/README.md index ec66ca967..1cd1810a5 100644 --- a/rfc/0000-template/README.md +++ b/rfc/0000-template/README.md @@ -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 diff --git a/rfc/README.md b/rfc/README.md index 67a643848..96296e5fe 100644 --- a/rfc/README.md +++ b/rfc/README.md @@ -2,16 +2,16 @@ 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 @@ -19,7 +19,7 @@ OpenShell has several places where design information lives. Use this guide to p | 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 | @@ -61,7 +61,7 @@ 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 --- ``` @@ -69,7 +69,7 @@ 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: