From 9672cd3994011869ddc194a8cc377891220a8d41 Mon Sep 17 00:00:00 2001 From: Cam Findlay Date: Wed, 29 Apr 2015 13:54:02 +1200 Subject: [PATCH] DOCS SilverStripe core RFC process, template and archive links to past RFCs. --- .../05_Contributing/02_Request_for_comment.md | 50 +++++++++++++++++++ ...lease_Process.md => 03_Release_Process.md} | 0 ...3_Documentation.md => 04_Documentation.md} | 0 ...{04_Translations.md => 05_Translations.md} | 0 ...n_Process.md => 06_Translation_Process.md} | 0 ...re_committers.md => 07_Core_committers.md} | 0 ...de_of_conduct.md => 08_Code_of_conduct.md} | 0 7 files changed, 50 insertions(+) create mode 100644 docs/en/05_Contributing/02_Request_for_comment.md rename docs/en/05_Contributing/{02_Release_Process.md => 03_Release_Process.md} (100%) rename docs/en/05_Contributing/{03_Documentation.md => 04_Documentation.md} (100%) rename docs/en/05_Contributing/{04_Translations.md => 05_Translations.md} (100%) rename docs/en/05_Contributing/{05_Translation_Process.md => 06_Translation_Process.md} (100%) rename docs/en/05_Contributing/{06_Core_committers.md => 07_Core_committers.md} (100%) rename docs/en/05_Contributing/{07_Code_of_conduct.md => 08_Code_of_conduct.md} (100%) diff --git a/docs/en/05_Contributing/02_Request_for_comment.md b/docs/en/05_Contributing/02_Request_for_comment.md new file mode 100644 index 000000000..a2d716635 --- /dev/null +++ b/docs/en/05_Contributing/02_Request_for_comment.md @@ -0,0 +1,50 @@ +# Request for comment (RFC) + +## Why RFCs? +This is part of the SilverStripe core decision-making process and addresses the gap between the idea phase and the pull request submission (and merge). + +The rationale behind this process is to: + * Encourage visibility on decision making + * Clarity on what the proposal is, its rationale and impact + * Reduce unnecessary work when coding large features is done without community and core-committers buy-in + * Improved likelihood of an optimal solution being merged + +The important thing to understand about the RFCs is that these are NOT a way to request features. Rather, they are a way to bring clarity so people understand what change is being proposed. + +## When to write an RFC? + +We intend RFCs to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into SilverStripe. The RFC author is responsible for building consensus within the community and documenting dissenting opinions. + +Before writing the actual summary RFC document, the idea should have already had a wide range of discussion in various community communication channels. Once discussions reach a point where you think most of the difficulties have been worked through then create the RFC using the template provided. + +The benefits of writing an RFC for non-trivial feature proposals are: + * Obtaining a preliminary approval from core-committers on an architecture before code is completed, to mitigate the risk of a non-merge after a PR is submitted + * Community becomes aware of incoming changes prior to the implementation + * RFC can be used as a basis for documentation of the feature + +## How to write an RFC? +### Template +The following heading can act as a template to starting your RFC. + * **Introduction** - include a reference #, title, author + * **Metadata** - standardised header containing at least the Author(s), Status and Version fields. + * **Purpose and outcome** - the purpose of this document, and the expected outcome. + * **Motivation** - why this is a good idea + * **Proposal** - how you propose to implement the idea after community discussion + * **Alternatives** - what other approaches were considered during the community discussion phase and why they were not chosen + * **Impact** - How will this change potentially impact on SilverStripe core? The good and the bad. + +### Submitting +Once complete submit the RFC in the prescribed format above as a GitHub issue as markdown. A core committer will add a tag to your RFC to keep track of the submissions and status (see links to filtered GitHub issues at the bottom of this document). The GitHub Issue will be closed once a pull request containing the feature gets merged. + +## What next? +The RFC will be raised and discussed by the core committers in the monthly Google Hangout sessions, a vote for accepting the RFC will be taken requiring a majority vote (with at least a quorum of more than half of the core committers present). + +Once approved it will be announced on the [developer list](https://groups.google.com/forum/#!forum/silverstripe-dev) and if relevant, [UserVoice](http://silverstripe.uservoice.com) and [Roadmap](https://www.silverstripe.org/software/roadmap) will be updated. This now means that if a pull request meeting the idea set out in the RFC was raised that it would be merged by the Core Committers (pending the usual code peer review). + +## RFC Archives + +[Proposed RFC drafts](https://github.com/silverstripe/silverstripe-framework/labels/rfc%2Fdraft) + + +[Accepted by Core Committers](https://github.com/silverstripe/silverstripe-framework/labels/rfc%2Faccepted) + diff --git a/docs/en/05_Contributing/02_Release_Process.md b/docs/en/05_Contributing/03_Release_Process.md similarity index 100% rename from docs/en/05_Contributing/02_Release_Process.md rename to docs/en/05_Contributing/03_Release_Process.md diff --git a/docs/en/05_Contributing/03_Documentation.md b/docs/en/05_Contributing/04_Documentation.md similarity index 100% rename from docs/en/05_Contributing/03_Documentation.md rename to docs/en/05_Contributing/04_Documentation.md diff --git a/docs/en/05_Contributing/04_Translations.md b/docs/en/05_Contributing/05_Translations.md similarity index 100% rename from docs/en/05_Contributing/04_Translations.md rename to docs/en/05_Contributing/05_Translations.md diff --git a/docs/en/05_Contributing/05_Translation_Process.md b/docs/en/05_Contributing/06_Translation_Process.md similarity index 100% rename from docs/en/05_Contributing/05_Translation_Process.md rename to docs/en/05_Contributing/06_Translation_Process.md diff --git a/docs/en/05_Contributing/06_Core_committers.md b/docs/en/05_Contributing/07_Core_committers.md similarity index 100% rename from docs/en/05_Contributing/06_Core_committers.md rename to docs/en/05_Contributing/07_Core_committers.md diff --git a/docs/en/05_Contributing/07_Code_of_conduct.md b/docs/en/05_Contributing/08_Code_of_conduct.md similarity index 100% rename from docs/en/05_Contributing/07_Code_of_conduct.md rename to docs/en/05_Contributing/08_Code_of_conduct.md