workflow: introducing RFC process. (#1089)

README.md

@@ -104,6 +104,8 @@ yarn dev  # serves VuePress' own docs with itself
 yarn test # make sure your code change pass the test
 ```
 
+If you intend to make `"substantial"` changes to VuePress or its documentation, please checkout [VuePress RFCs](./rfcs/README.md).
+
 ## License
 
 [MIT](https://github.com/vuejs/vuepress/blob/master/LICENSE)

rfcs/README.md

@@ -0,0 +1,36 @@
+# VuePress RFCs
+
+Many changes, including bug fixes and documentation improvements can be implemented and reviewed via the normal GitHub pull request workflow.
+
+Some changes though are "substantial", and we ask that these be put through a bit of a design process and produce a consensus among the VuePress core team.
+
+The "RFC" (request for comments) process is intended to provide a consistent and controlled path for new features to enter the project.
+
+## When to follow this process
+
+You should consider using this process if you intend to make `"substantial"` changes to VuePress or its documentation.
+
+## The RFC life-cycle
+
+- Fork this repo https://github.com/vuejs/vuepress.
+- Copy `rfcs/template.md` to `rfcs/text/0000-feature.md` (where 'feature' is descriptive. Don't assign an RFC number yet).
+- Fill in the RFC. Put care into the details.
+- Submit a pull request.
+- Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those that don't receive any comments.
+- Finally, the team will decide whether the RFC is a `'candidate'` for inclusion in VuePress.
+- Once an RFC becomes `'candidate'`, it will enter a `'final stage'` lasting 7 calendar days.
+- An RFC can be **modified** based upon feedback from the team and community.
+- An RFC may be **rejected** by the team after public discussion has settled and comments have been made summarizing the rationale for rejection. A member of the team should then close the RFCs associated pull request.
+- An RFC may be **accepted** at the close of its `'final stage'`. A team member will merge the RFCs associated pull request, at which point the RFC will become `'active'`.
+- Once an RFC becomes `'active'`, a team member will open an issue for the implmentation request, then authors may implement it and submit a pull request to the VuePress repo.
+- An `'active'` RFC implementation pull request will ONLY be merged when it passes the review of core members. Once the implmentation is merged, the corresponding issue will be closed  and the RFC will enter the `'finished'` stage.
+- An `'active'` RFC that no one follows in a month will be tagged `'inactive'`. It will remain `'inactive'` unless someone opens a pull request.
+
+## Notes
+
+- The author of an RFC is not obligated to implement it. Of course, the RFC author (like any other developer) is welcome to post an implementation for review after the RFC has been accepted.
+- If you are interested in working on the implementation for an `'active'` RFC, but cannot determine if someone else is already working on it, feel free to ask (e.g. by leaving a comment on the associated issue).
+- It's worth noting that even if RFC becomes `'active'`, it doesn't mean that the pull request of this implementation will eventually be merged.
+- **VuePress's RFC process owes its inspiration to the [Yarn RFC process]**.
+
+[Yarn RFC process]: https://github.com/yarnpkg/rfcs

rfcs/template.md

@@ -0,0 +1,53 @@
+- Start Date: (fill me in with today's date, YYYY-MM-DD)
+- RFC PR: (leave this empty)
+- VuePress Issue: (leave this empty)
+
+# Summary
+
+Brief explanation of the feature.
+
+# Basic example
+
+If the proposal involves a new or changed API, include a basic code example. Omit this section if it's not applicable.
+
+# Motivation
+
+Why are we doing this? What use cases does it support? What is the expected outcome?
+
+Please focus on explaining the motivation so that if this RFC is not accepted, the motivation could be used to develop alternative solutions. In other words, enumerate the constraints you are trying to solve without coupling them too closely to the solution you have in mind.
+
+# Detailed design
+
+This is the bulk of the RFC. Explain the design in enough detail for somebody familiar with VuePress to understand, and for somebody familiar with the implementation to implement. This should get into specifics and corner-cases, and include examples of how the feature is used. Any new terminology should be defined here.
+
+# Drawbacks
+
+Why should we *not* do this? Please consider:
+
+- implementation cost, both in term of code size and complexity
+- whether the proposed feature can be implemented in user space
+- the impact on teaching people VuePress
+- integration of this feature with other existing and planned features
+- cost of migrating existing VuePress applications (is it a breaking change?)
+
+There are tradeoffs to choosing any path. Attempt to identify them here.
+
+# Alternatives
+
+What other designs have been considered? What is the impact of not doing this?
+
+# Adoption strategy
+
+If we implement this proposal, how will existing VuePress developers adopt it? Is this a breaking change?
+
+# How we teach this
+
+What names and terminology work best for these concepts and why? How is this idea best presented? As a continuation of existing VuePress patterns?
+
+Would the acceptance of this proposal mean the VuePress documentation must be re-organized or altered? Does it change how VuePress is taught to new developers at any level?
+
+How should this feature be taught to existing VuePress developers?
+
+# Unresolved questions
+
+Optional, but suggested for first drafts. What parts of the design are still TBD?