You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This document will outline the process in which React Router will continue to evolve, and how new features will make their way into the codebase. This is an evergreen document and will be updated as-needed to reflect future changes in the process.
23
+
This document will outline the process in which React Router will continue to evolve and how new features will make their way into the codebase. This is an evergreen document and will be updated asneeded to reflect future changes in the process.
24
24
25
25
## Design Goals
26
26
27
27
The following design goals should be considered when considering RFCs for acceptance:
28
28
29
-
-**Less is More**. React Router has gained a _lot_ of functionality in the past years, but with that comes a bunch of new API surface. It's time to hone in on the core functionality and aim to reduce API surface _without sacrificing capabilities_. This may come in multiple forms, such as condensing a few existing APIs into a singular API, or deprecating a current APIs in favor of a new React API.
30
-
-**Routing and Data Focused.** Focus on core router-integrated/router-centric APIs and avoid adding firstclass APIs that can be implemented in user-land
31
-
-**Simple Migration Paths.** Major version upgrade's don't have to stink. Breaking changes should be implemented behind future flags. Deprecations should be properly marked ahead of time in code and in documentation. Console warnings should be added prior to major releases to nudge developers towards the changes they can begin make to prep for the upgrade.
29
+
-**Less is More**. React Router has gained a _lot_ of functionality in the past years, but with that comes a bunch of new API surface. It's time to hone in on the core functionality and aim to reduce API surface _without sacrificing capabilities_. This may come in multiple forms, such as condensing a few existing APIs into a singular API, or deprecating current APIs in favor of a new React API.
30
+
-**Routing and Data Focused.** Focus on core router-integrated/router-centric APIs and avoid adding first-class APIs that can be implemented in user-land
31
+
-**Simple Migration Paths.** Major version upgrade's don't have to stink. Breaking changes should be implemented behind future flags. Deprecations should be properly marked ahead of time in code and in documentation. Console warnings should be added prior to major releases to nudge developers towards the changes they can begin to make to prep for the upgrade.
32
32
-**Lowest Common Mode.** Features are added at the lowest mode possible (`declarative -> data -> framework`) and then leveraged by the higher-level modes. This ensures that the largest number of React Router applications can leverage them.
33
33
-**Regular Release Cadence**. Aim for major SemVer releases on a ~yearly basis so application developers can prepare in advance.
34
34
@@ -44,18 +44,18 @@ The SC will initially consist of the Remix team developers:
44
44
- Jacob Ebey
45
45
- Brooks Lybrand
46
46
47
-
In the future, we may also add a limited number of heavily-involved community members to the SC as well.
47
+
In the future, we may add a limited number of heavilyinvolved community members to the SC as well.
48
48
49
-
In order to reduce friction the SC will primarily operate asynchronously via Github but private and/or public meetings may be scheduled as needed.
49
+
To reduce friction, the SC will primarily operate asynchronously via GitHub, but private and/or public meetings may be scheduled as needed.
50
50
51
51
## Bug/Issue Process
52
52
53
-
Due to the # of React Router applications out there, we have to be a bit strict on the process for filing issues to avoid an overload in Github.
53
+
Due to the # of React Router applications out there, we have to be a bit strict on the process for filing issues to avoid an overload in GitHub.
54
54
55
55
-**All** bugs must have a **minimal** reproduction [^3]
56
56
- Minimal means that it is not just pointing to a deployed site or a branch in your existing application
57
57
- The preferred method is StackBlitz via [https://reactrouter.com/new](https://reactrouter.com/new)
58
-
- If Stackblitz is not an option, a Github repo based on a fresh `create-react-router` app is acceptable
58
+
- If Stackblitz is not an option, a GitHub repo based on a fresh `create-react-router` app is acceptable
59
59
- Only in extraordinary circumstances will code snippets or maximal reproductions be accepted
60
60
- Issue Review
61
61
- Issues not meeting the above criteria will be closed and pointed to this document
@@ -64,17 +64,17 @@ Due to the # of React Router applications out there, we have to be a bit strict
64
64
- Fixing Issues
65
65
- The SC will mark good community issues with an `Accepting PRs` label
66
66
- These issues will generally be ones that are likely to have a small surface area fix
67
-
- However, anyone can work on any issue but there's no guarantee the PR will be accepted if the surface area is too large for expedient review by a core team member
67
+
- However, anyone can work on any issue, but there's no guarantee the PR will be accepted if the surface area is too large for expedient review by a core team member
The process for new features being added to React Router will follow a series of stages loosely based on the [TC39 Process](https://tc39.es/process-document/). It is important to note that entrance into any given stage does not imply that an RFC will proceed any further. The stages will act as a funnel with fewer RFCs making it into subsequent stages such that only the strongest RFCs make it into a React Router release in a stable fashion. This table gives a high-level overview of the Stages but please see the individual stage sections below for more detailed information on the stages and the process for moving an FC through them.
73
+
The process for new features being added to React Router will follow a series of stages loosely based on the [TC39 Process](https://tc39.es/process-document/). It is important to note that entrance into any given stage does not imply that an RFC will proceed any further. The stages will act as a funnel with fewer RFCs making it into later stages such that only the strongest RFCs make it into a React Router release in a stable fashion. This table gives a high-level overview of the Stages, but please see the individual stage sections below for more detailed information on the stages and the process for moving an FC through them.
| 0 | Proposal | Proposal discussion opened on Github| We start with a Github Proposal to provide the lowest barrier to RFC submission. Anyone can submit an RFC and community members can review, comment, up-vote without any initial involvement of the SC. |
77
+
| 0 | Proposal | Proposal discussion opened on GitHub| We start with a GitHub Proposal to provide the lowest barrier to RFC submission. Anyone can submit an RFC and community members can review, comment, up-vote without any initial involvement of the SC. |
78
78
| 1 | Consideration | Proposal acceptance from 2 or more SC members | The consideration phase is the first "funnel" for incoming RFCs where the SC can officially express interest in the more popular RFCs. We only require 2 SC members to express interest to move an RFC into the **Consideration** phase to allow for low-friction experimentation of features in the **Alpha** stage. |
79
79
| 2 | Alpha | Pull-Request (PR) opened to implement the feature in an "unstable" state. This should be accompanied by a mechanism for community members to test the feature via [pkg.pr.new](https://pkg.pr.new/), [patch-package](https://www.npmjs.com/package/patch-package), or [pnpm patch](https://pnpm.io/cli/patch)| The **Alpha** stage is the next funnel for RFCs. Once interest has been expressed by the SC in the **Consideration** phase we open the RFC up for a sample PR implementation and a mechanism for community members to alpha test the feature without requiring that anything be shipped in a React Router SemVer release. This stage allows evaluation of the RFC in running applications and consideration of what a practical implementation of the RFC looks like in the code. |
80
80
| 3 | Beta | PR approval from at least 50% of the SC members indicating their acceptance of the PR for an unstable API | A RFC enters the **Beta** stage once enough members of the SC feel comfortable not only with the code for the beta feature, but have also seen positive feedback from alpha testers that the feature is working as expected. Once an **Alpha** stage PR has enough SC approvals, it will be merged and be included in the next React Router release. |
@@ -85,28 +85,28 @@ To get a feature accepted and implemented in React Router, it will go through th
85
85
86
86
## New Feature Stages
87
87
88
-
### Stage 0 - Proposal
88
+
### Stage 0 — Proposal
89
89
90
-
- All new features begin at **Stage 0 - Proposal** when a Request For Comments (RFC) is written up in a GitHub Proposal Discussion
90
+
- All new features begin at **Stage 0 — Proposal** when a Request For Comments (RFC) is written up in a GitHub Proposal Discussion
91
91
- Anyone can write an RFC, including core team members and community members
92
92
- The RFC should outline the use-case for the new feature, why current APIs are insufficient for the use-case, and provide potential API surfaces for the feature
93
93
- The proposal should be clear, concise, and provide enough context for the Steering Committee (SC) and community to evaluate its merit
94
-
- Community upvotes on the proposal are used as a signal of interest and demand for the SC - higher upvoted issues are more likely to be considered by the SC members
94
+
- Community upvotes on the proposal are used as a signal of interest and demand for the SC — higher upvoted issues are more likely to be considered by the SC members
95
95
- At this stage, community members may feel free to work on sample implementations in a fork of the repo and provide links in the RFC, but a pull request **should not** be opened until it reaches Stage 1
96
96
97
-
### Stage 1 - Consideration
97
+
### Stage 1 — Consideration
98
98
99
-
- A proposal enters **Stage 1 - Consideration** when two or more SC members indicate interest/support for the idea as a valuable addition to React Router
100
-
- Upon entering this stage, a Github Issue will be created for the feature and added to the roadmap
99
+
- A proposal enters **Stage 1 — Consideration** when two or more SC members indicate interest/support for the idea as a valuable addition to React Router
100
+
- Upon entering this stage, a GitHub Issue will be created for the feature and added to the roadmap
101
101
- These initial supporting SC members will be the champions for the feature and will be loosely responsible for shepherding the feature through the stages of the RFC process
102
102
- At this stage, the proposal is eligible for a sample PR implementation from a core team or community member
103
103
- The SC will indicate at this stage if this is a feature open to a community PR or something the core team would prefer to tackle
104
104
- All PRs at this stage should implement the feature in an "unstable" fashion (usually using an `unstable_` prefix on the future flag or API)
105
105
106
-
### Stage 2 - Alpha
106
+
### Stage 2 — Alpha
107
107
108
-
- A proposal enters **Stage 2 - Alpha** once a PR has been opened implementing the feature in an `unstable_` state
109
-
- At this stage, we are looking for early community testing _before_ merging any work to the React Router repo - so these PRs should provide a mechanism for community members to opt-into to alpha testing
108
+
- A proposal enters **Stage 2 — Alpha** once a PR has been opened implementing the feature in an `unstable_` state
109
+
- At this stage, we are looking for early community testing _before_ merging any work to the React Router repo — so these PRs should provide a mechanism for community members to opt-into to alpha testing
110
110
- Ideally, we'll be able to wire up [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new) on the repo
111
111
- Otherwise, a `.patch` file (or instructions to create one) can be included in the PR for use with [patch-package](https://www.npmjs.com/package/patch-package) or [pnpm patch](https://pnpm.io/cli/patch)
112
112
- Feedback from alpha testers is considered essential for further progress
@@ -118,24 +118,24 @@ To get a feature accepted and implemented in React Router, it will go through th
118
118
- Code is not required to be in a final state yet, but it must be coded in such a way so as not to introduce regressions to other areas of the API
119
119
- We have seen enough positive feedback from Alpha testers to move the feature along
120
120
121
-
### Stage 3 - Beta
121
+
### Stage 3 — Beta
122
122
123
-
- A proposal enters **Stage 3 - Beta** once it receives **Stage 2 - Alpha** PR approvals from at least 50% of the SC members and is merged to `dev`
123
+
- A proposal enters **Stage 3 — Beta** once it receives **Stage 2 — Alpha** PR approvals from at least 50% of the SC members and is merged to `dev`
124
124
- This will include the feature in `nightly` releases and the next normal SemVer release for broader beta testing under the `unstable_` flag
125
125
126
-
### Stage 4 - Stabilization
126
+
### Stage 4 — Stabilization
127
127
128
-
- A proposal enters **Stage 4 - Stabilization** after a minimum of 1 month in **Stage 3 - Beta** and a PR has been opened to remove the `unstable_` prefixes and stabilize the feature
128
+
- A proposal enters **Stage 4 — Stabilization** after a minimum of 1 month in **Stage 3 — Beta** and a PR has been opened to remove the `unstable_` prefixes and stabilize the feature
129
129
- Stabilization PRs should add proper documentation for the feature
130
130
- SC members will review and approve the PR via GitHub reviews
131
131
- Approval at this stage communicates:
132
132
- Sufficient community feedback has been received from beta testers to trust the API's design and implementation
133
133
- The code is production-quality and well-tested, with no related regressions
134
134
- The PR includes documentation for the stable feature
135
135
136
-
### Stage 5 - Stable
136
+
### Stage 5 — Stable
137
137
138
-
- A proposal is enters **Stage 5 - Stable** once it receives **Stage 4** PR approvals from at least 50% of the SC members and is merged to `dev`
138
+
- A proposal enters **Stage 5 — Stable** once it receives **Stage 4 — Stabilization** PR approvals from at least 50% of the SC members and is merged to `dev`
139
139
- This will include the stable feature in `nightly` releases and the next normal SemVer release
0 commit comments