|
2 | 2 |
|
3 | 3 | 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. |
4 | 4 |
|
5 | | -## Start with a GitHub Discussion |
| 5 | +## Start with a GitHub issue |
6 | 6 |
|
7 | | -Before writing an RFC, consider opening a [GitHub Discussion](https://github.com/NVIDIA/OpenShell/discussions) to gauge interest and get early feedback. This helps: |
| 7 | +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: |
8 | 8 |
|
9 | 9 | - Validate that the problem is worth solving |
10 | 10 | - Surface potential concerns early |
11 | 11 | - Build consensus before investing in a detailed proposal |
12 | 12 | - Identify the right reviewers and stakeholders |
13 | 13 |
|
14 | | -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. |
| 14 | +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. |
15 | 15 |
|
16 | 16 | ## RFCs vs other artifacts |
17 | 17 |
|
18 | 18 | OpenShell has several places where design information lives. Use this guide to pick the right one: |
19 | 19 |
|
20 | 20 | | Artifact | Purpose | When to use | |
21 | 21 | |----------|---------|-------------| |
22 | | -| **GitHub Discussion** | Gauge interest in a rough idea | You have a thought but aren't sure it's worth a proposal yet | |
| 22 | +| **GitHub issue** | Track and scope a rough idea | You have a thought but aren't sure it's worth a proposal yet | |
23 | 23 | | **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 | |
24 | 24 | | **RFC** | Propose a cross-cutting decision that needs broad consensus | Architectural changes, API contracts, process changes, or anything that spans multiple components or teams | |
25 | 25 | | **Architecture doc** (`architecture/`) | Document how things work today | Living reference material — updated as the system evolves | |
@@ -61,15 +61,15 @@ authors: |
61 | 61 | state: draft |
62 | 62 | links: |
63 | 63 | - https://github.com/NVIDIA/OpenShell/pull/123 |
64 | | - - https://github.com/NVIDIA/OpenShell/discussions/456 |
| 64 | + - https://github.com/NVIDIA/OpenShell/issues/456 |
65 | 65 | --- |
66 | 66 | ``` |
67 | 67 |
|
68 | 68 | We track the following metadata: |
69 | 69 |
|
70 | 70 | - **authors**: The authors (and therefore owners) of an RFC. Listed as GitHub usernames. |
71 | 71 | - **state**: Must be one of the states discussed below. |
72 | | -- **links**: Related PRs, discussions, or issues. Add entries as the RFC progresses. |
| 72 | +- **links**: Related PRs or issues. Add entries as the RFC progresses. |
73 | 73 | - **superseded_by**: *(optional)* For RFCs in the `superseded` state, the RFC number that replaces this one (e.g., `0005`). |
74 | 74 |
|
75 | 75 | An RFC can be in one of the following states: |
|
0 commit comments