From 72eceeda76b894331eaa9b61d4efc82da1a33250 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 15 Jun 2026 16:17:37 -0700 Subject: [PATCH 1/9] docs(rfc): require issues before RFCs Signed-off-by: Drew Newberry --- .github/ISSUE_TEMPLATE/feature_request.yml | 4 +- AGENTS.md | 1 + CONTRIBUTING.md | 2 +- architecture/README.md | 4 +- rfc/0000-template/README.md | 6 ++- rfc/README.md | 45 +++++++++++++--------- 6 files changed, 37 insertions(+), 25 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index bdf2cacc1..bbc1188d7 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -7,7 +7,9 @@ body: value: | ## Design-First Feature Proposals - OpenShell feature requests must include a design proposal — describe the system behavior you want, not just the outcome. If your agent explored the codebase to assess feasibility (e.g., using the `create-spike` skill), include its findings. + OpenShell feature requests must include a design proposal — describe the system behavior you want, not just the outcome. New features start here, not as RFC pull requests. If maintainers decide an RFC is necessary, they will request one from this issue and assign the RFC number. + + If your agent explored the codebase to assess feasibility (e.g., using the `create-spike` skill), include its findings. - type: textarea id: problem diff --git a/AGENTS.md b/AGENTS.md index fabc41797..53b4e8049 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -62,6 +62,7 @@ These pipelines connect skills into end-to-end workflows. Individual skill files - **Bug reports** must include an agent diagnostic section — proof that the reporter's agent investigated the issue before filing. See the issue template. - **Feature requests** must include a design proposal, not just a "please build this" request. See the issue template. +- **New features** must start as GitHub issues using the feature request template. Open an RFC only after an issue exists; maintainers decide when one is needed and assign RFC numbers from the issue. - **PRs** must follow the PR template structure: Summary, Related Issue, Changes, Testing, Checklist. - **PRs from unvouched external contributors** are automatically closed. See the Vouch System section above. - **Security vulnerabilities** must NOT be filed as GitHub issues. Follow [SECURITY.md](SECURITY.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 07ce1d916..74977f318 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -223,7 +223,7 @@ These are the primary `mise` tasks for day-to-day development: ## RFCs -For cross-cutting architectural decisions, API contract changes, or process proposals that need broad consensus, use the RFC process. RFCs live in `rfc/` — copy the template, fill it in, and open a PR for discussion. See [rfc/README.md](rfc/README.md) for the full lifecycle and guidelines on when to write an RFC versus a spike issue or architecture doc. +New features always start as GitHub issues using the feature request template. For cross-cutting architectural decisions, API contract changes, or process proposals that need broad consensus, maintainers may ask for an RFC from the issue and assign an RFC number there. RFCs live in `rfc/`, but they should be uncommon. See [rfc/README.md](rfc/README.md) for the full lifecycle and guidelines on when an issue should become an RFC versus a spike issue or architecture doc. ## Documentation diff --git a/architecture/README.md b/architecture/README.md index 5a1d82831..f8961a938 100644 --- a/architecture/README.md +++ b/architecture/README.md @@ -169,8 +169,8 @@ that crate's `README.md`. ## `rfc/` vs `architecture/` -For broad design proposals, use `rfc/`. Once an RFC is adopted, appropriate details should be written back to architecture docs. +Broad design proposals start as GitHub issues. If maintainers decide a proposal needs broad consensus, they assign an RFC number from the issue and the RFC lives in `rfc/`. Once an RFC is adopted, appropriate details should be written back to architecture docs. `architecture/` serves as the canonical reference for OpenShell's design and architecture. -`rfc` serves to help facilitate discussion and ensure features are appropriately designed. These are useful for understanding the context in which certain architecture designs were made. +`rfc` serves to help facilitate discussion and ensure the few changes that need that level of review are appropriately designed. These are useful for understanding the context in which certain architecture designs were made. diff --git a/rfc/0000-template/README.md b/rfc/0000-template/README.md index 1cd1810a5..4ce294046 100644 --- a/rfc/0000-template/README.md +++ b/rfc/0000-template/README.md @@ -3,13 +3,15 @@ authors: - "@your-github-username" state: draft links: - - (related PRs or issues) + - (originating GitHub issue where maintainers assigned this RFC number) --- # RFC NNNN - Your Title Here ## Summary diff --git a/rfc/README.md b/rfc/README.md index 96296e5fe..64c844769 100644 --- a/rfc/README.md +++ b/rfc/README.md @@ -1,17 +1,19 @@ # OpenShell RFCs -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. +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](https://github.com/NVIDIA/OpenShell/issues/new/choose), not as an RFC pull request. Most proposals should stay in the issue, spike, and pull request workflow. RFCs are intentionally rare and are reserved for changes that are cross-cutting, potentially controversial, or significant enough that stakeholders should weigh in before code is written. + +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, 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: +Before writing an RFC, you must open a [GitHub issue](https://github.com/NVIDIA/OpenShell/issues/new/choose) 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 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 maintainers decide the idea needs broad design review, they will ask for an RFC from that issue. Maintainers assign the RFC number in the issue before the RFC is created, preventing number clashes across branches. ## RFCs vs other artifacts @@ -19,16 +21,16 @@ OpenShell has several places where design information lives. Use this guide to p | Artifact | Purpose | When to use | |----------|---------|-------------| -| **GitHub issue** | Track and scope a rough idea | You have a thought but aren't sure it's worth a proposal yet | +| **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 | Architectural changes, API contracts, process changes, or anything that spans multiple components or teams | +| **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 -The following are examples of when an RFC is appropriate: +RFCs should be uncommon. 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 @@ -44,11 +46,12 @@ 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 spike issue is the right vehicle. +If a change doesn't require cross-team consensus, a GitHub issue or spike issue is the right vehicle. ## RFC metadata and state @@ -60,8 +63,8 @@ authors: - "@username" state: draft links: - - https://github.com/NVIDIA/OpenShell/pull/123 - https://github.com/NVIDIA/OpenShell/issues/456 + - https://github.com/NVIDIA/OpenShell/pull/123 --- ``` @@ -69,7 +72,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 or issues. Add entries as the RFC progresses. +- **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: @@ -85,11 +88,15 @@ An RFC can be in one of the following states: ## RFC lifecycle -### 1. Reserve an RFC number +### 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 -Look at the existing RFC folders in this directory and choose the next available number. If two authors happen to pick the same number on separate branches, the conflict is resolved during PR review — the later PR simply picks the next available number. +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. Authors should use the assigned number instead of choosing one locally. -### 2. Create your RFC +### 3. Create your RFC Each RFC lives in its own folder: @@ -99,7 +106,7 @@ rfc/NNNN-my-feature/ (optional: diagrams, images, supporting files) ``` -Where `NNNN` is your 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. +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: @@ -107,27 +114,27 @@ To start a new RFC, copy the template folder: cp -r rfc/0000-template rfc/NNNN-my-feature ``` -Fill in the metadata and start writing. The state should be `draft` while you're iterating. +Fill in the metadata, include the originating issue in `links`, and start writing. The state should be `draft` while you're iterating. -### 3. Open a pull request +### 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 the `pr` field in the metadata. +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. The PR is where discussion happens. Anyone subscribed to the repo will get a notification and can read your RFC and provide feedback. -### 4. Iterate and build consensus +### 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. -### 5. Merge the pull request +### 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. 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! -### 6. Implementation +### 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. From 6a6f92bf17623d72cc654e94b408a7b5548c0d0d Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 15 Jun 2026 16:22:45 -0700 Subject: [PATCH 2/9] docs(rfc): correct RFC statuses Signed-off-by: Drew Newberry --- rfc/0001-core-architecture/README.md | 2 +- rfc/0002-agent-driven-policy-management/README.md | 2 +- rfc/0003-gateway-configuration/README.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/rfc/0001-core-architecture/README.md b/rfc/0001-core-architecture/README.md index 0a3af73a8..d804bdf7a 100644 --- a/rfc/0001-core-architecture/README.md +++ b/rfc/0001-core-architecture/README.md @@ -1,7 +1,7 @@ --- authors: - "@drew" -state: review +state: accepted --- # RFC 0001 - Core Architecture diff --git a/rfc/0002-agent-driven-policy-management/README.md b/rfc/0002-agent-driven-policy-management/README.md index 9a1e3c4aa..b55c7e98f 100644 --- a/rfc/0002-agent-driven-policy-management/README.md +++ b/rfc/0002-agent-driven-policy-management/README.md @@ -1,7 +1,7 @@ --- authors: - "@alwatson" -state: draft +state: accepted links: - https://github.com/NVIDIA/OpenShell/issues/1062 - https://github.com/NVIDIA/OpenShell/blob/main/architecture/policy-advisor.md diff --git a/rfc/0003-gateway-configuration/README.md b/rfc/0003-gateway-configuration/README.md index 83ac5d4a6..7bc4b8f08 100644 --- a/rfc/0003-gateway-configuration/README.md +++ b/rfc/0003-gateway-configuration/README.md @@ -1,7 +1,7 @@ --- authors: - "@TaylorMutch" -state: review +state: implemented --- # RFC 0003 - Gateway Configuration File From 29a2dcf0874abfb5c636a2ea4385b76d09095ff2 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Mon, 15 Jun 2026 16:26:28 -0700 Subject: [PATCH 3/9] docs(rfc): mark template accepted Signed-off-by: Drew Newberry --- rfc/0000-template/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/0000-template/README.md b/rfc/0000-template/README.md index 4ce294046..214baf22f 100644 --- a/rfc/0000-template/README.md +++ b/rfc/0000-template/README.md @@ -1,7 +1,7 @@ --- authors: - "@your-github-username" -state: draft +state: accepted links: - (originating GitHub issue where maintainers assigned this RFC number) --- From b2ca3202afdf33a4b9195669d15649cc14546361 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 16 Jun 2026 07:55:49 -0700 Subject: [PATCH 4/9] Update rfc/README.md Co-authored-by: krishicks --- rfc/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/README.md b/rfc/README.md index 64c844769..0a30a778f 100644 --- a/rfc/README.md +++ b/rfc/README.md @@ -1,6 +1,6 @@ # 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](https://github.com/NVIDIA/OpenShell/issues/new/choose), not as an RFC pull request. Most proposals should stay in the issue, spike, and pull request workflow. RFCs are intentionally rare and are reserved for changes that are cross-cutting, potentially controversial, or significant enough that stakeholders should weigh in before code is written. +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](https://github.com/NVIDIA/OpenShell/issues/new/choose), not as an RFC pull request. RFCs are intentionally rare and are reserved for changes that are cross-cutting, potentially controversial, or significant enough that stakeholders should weigh in before code is written. 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. From 04930af5090721fd36b4dc756ea6467a8559eee1 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 16 Jun 2026 07:59:16 -0700 Subject: [PATCH 5/9] docs(rfc): document accepted RFC project tracking Signed-off-by: Drew Newberry --- README.md | 1 + rfc/README.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/README.md b/README.md index fbf5da394..7840ab4e9 100644 --- a/README.md +++ b/README.md @@ -237,6 +237,7 @@ All implementation work is human-gated — agents propose plans, humans approve, - [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 +- [RFC Board](https://github.com/orgs/NVIDIA/projects/233/views/6) — accepted RFCs tracked on the OpenShell Roadmap with the `rfc` label - [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/README.md b/rfc/README.md index 0a30a778f..be8fab198 100644 --- a/rfc/README.md +++ b/rfc/README.md @@ -132,6 +132,8 @@ RFCs rarely go through this process unchanged. Make edits as new commits to the 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 track it in the OpenShell Roadmap GitHub project and add the `rfc` label so it appears on the [RFC board](https://github.com/orgs/NVIDIA/projects/233/views/6). + 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 From a138b0ca64a9b702d710ac18a3c2eaee54c0f515 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 16 Jun 2026 16:12:02 -0700 Subject: [PATCH 6/9] docs(rfc): reframe RFC discussion guidance Signed-off-by: Drew Newberry --- rfc/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfc/README.md b/rfc/README.md index be8fab198..74d372670 100644 --- a/rfc/README.md +++ b/rfc/README.md @@ -1,6 +1,6 @@ # 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](https://github.com/NVIDIA/OpenShell/issues/new/choose), not as an RFC pull request. RFCs are intentionally rare and are reserved for changes that are cross-cutting, potentially controversial, or significant enough that stakeholders should weigh in before code is written. +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](https://github.com/NVIDIA/OpenShell/issues/new/choose), 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. @@ -30,7 +30,7 @@ The key distinction: **spikes investigate whether and how something can be done; ## When to use an RFC -RFCs should be uncommon. The following are examples of when maintainers may ask for one after an issue is opened: +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 From 1676124ec254bd449b8a5c8db181a5eb7663f8e4 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 16 Jun 2026 16:28:53 -0700 Subject: [PATCH 7/9] docs(rfc): label issues when assigning RFCs Signed-off-by: Drew Newberry --- rfc/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/README.md b/rfc/README.md index 74d372670..1414e11bb 100644 --- a/rfc/README.md +++ b/rfc/README.md @@ -94,7 +94,7 @@ Start with a GitHub issue. New features must use the feature request template an ### 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. Authors should use the assigned number instead of choosing one locally. +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 `rfc` label to the originating issue so RFC work is searchable. Authors should use the assigned number instead of choosing one locally. ### 3. Create your RFC From e51f6006146e322cec160136ef4bbcfc3c4718f4 Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 16 Jun 2026 16:30:20 -0700 Subject: [PATCH 8/9] docs(rfc): link labeled RFC issues to board Signed-off-by: Drew Newberry --- rfc/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/README.md b/rfc/README.md index 1414e11bb..b4cb9223a 100644 --- a/rfc/README.md +++ b/rfc/README.md @@ -94,7 +94,7 @@ Start with a GitHub issue. New features must use the feature request template an ### 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 `rfc` label to the originating issue so RFC work is searchable. Authors should use the assigned number instead of choosing one locally. +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 `rfc` label to the originating issue so RFC work appears on the [RFC board](https://github.com/orgs/NVIDIA/projects/233/views/6). Authors should use the assigned number instead of choosing one locally. ### 3. Create your RFC From e374b3f1ce8a90700c650b0a0d01765e1fb6271c Mon Sep 17 00:00:00 2001 From: Drew Newberry Date: Tue, 16 Jun 2026 16:44:01 -0700 Subject: [PATCH 9/9] docs(rfc): clarify RFC labels and board tracking Signed-off-by: Drew Newberry --- CONTRIBUTING.md | 2 +- README.md | 2 +- rfc/README.md | 8 ++++---- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 74977f318..ecf58e3f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -223,7 +223,7 @@ These are the primary `mise` tasks for day-to-day development: ## RFCs -New features always start as GitHub issues using the feature request template. For cross-cutting architectural decisions, API contract changes, or process proposals that need broad consensus, maintainers may ask for an RFC from the issue and assign an RFC number there. RFCs live in `rfc/`, but they should be uncommon. See [rfc/README.md](rfc/README.md) for the full lifecycle and guidelines on when an issue should become an RFC versus a spike issue or architecture doc. +New features always start as GitHub issues using the feature request template. For cross-cutting architectural decisions, API contract changes, or process proposals that need broad consensus, maintainers may ask for an RFC from the issue and assign an RFC number there. RFCs live in `rfc/`. See [rfc/README.md](rfc/README.md) for the full lifecycle and guidelines. ## Documentation diff --git a/README.md b/README.md index 7840ab4e9..2b9749652 100644 --- a/README.md +++ b/README.md @@ -237,7 +237,7 @@ All implementation work is human-gated — agents propose plans, humans approve, - [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 -- [RFC Board](https://github.com/orgs/NVIDIA/projects/233/views/6) — accepted RFCs tracked on the OpenShell Roadmap with the `rfc` label +- [RFC Board](https://github.com/orgs/NVIDIA/projects/233/views/6) — RFC proposals tracked on the OpenShell Roadmap with the `rfc` label - [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/README.md b/rfc/README.md index b4cb9223a..4a0072f5c 100644 --- a/rfc/README.md +++ b/rfc/README.md @@ -13,7 +13,7 @@ Before writing an RFC, you must open a [GitHub issue](https://github.com/NVIDIA/ - 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 in the issue before the RFC is created, preventing number clashes across branches. +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 @@ -94,7 +94,7 @@ Start with a GitHub issue. New features must use the feature request template an ### 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 `rfc` label to the originating issue so RFC work appears on the [RFC board](https://github.com/orgs/NVIDIA/projects/233/views/6). Authors should use the assigned number instead of choosing one locally. +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 @@ -118,7 +118,7 @@ Fill in the metadata, include the originating issue in `links`, and start writin ### 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. +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](https://github.com/orgs/NVIDIA/projects/233/views/6). The PR is where discussion happens. Anyone subscribed to the repo will get a notification and can read your RFC and provide feedback. @@ -132,7 +132,7 @@ RFCs rarely go through this process unchanged. Make edits as new commits to the 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 track it in the OpenShell Roadmap GitHub project and add the `rfc` label so it appears on the [RFC board](https://github.com/orgs/NVIDIA/projects/233/views/6). +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!