rfc: update the RFC process

cockroachdb · Aug 25, 2017 · 31b2d57 · 31b2d57
1 parent 90840ef
commit 31b2d57
Show file tree

Hide file tree

Showing 75 changed files with 149 additions and 25 deletions.
diff --git a/docs/RFCS/00000000_template.md b/docs/RFCS/00000000_template.md
@@ -0,0 +1,95 @@
+- Feature Name:
+- Status: draft/in-progress/completed/rejected/obsolete
+- Start Date: YYYY-MM-DD
+- Authors:
+- RFC PR: (PR # after acceptance of initial draft)
+- Cockroach Issue: (one or more # from the issue tracker)
+
+**Remember, you can submit a PR with your RFC before the text is
+complete. Refer to the [README](README.md#rfc-process) for details.**
+
+# Summary
+
+One paragraph explanation of the proposed change.
+
+Suggested contents:
+- What is being proposed
+- Why (short reason)
+- How (short plan)
+- Impact
+
+# Motivation
+
+Why are we doing this? What use cases does it support? What is the expected outcome?
+
+# Guide-level explanation
+
+How do we teach this?
+
+Explain the proposal as if it was already included in the project and
+you were teaching it to another CockroachDB programmer. That generally means:
+
+- Introducing new named concepts.
+- Explaining the feature largely in terms of examples.
+- Explaining how CockroachDB contributors and users should think about
+  the feature, and how it should impact the way they use
+  CockroachDB. It should explain the impact as concretely as possible.
+- If applicable, provide sample error messages, deprecation warnings, or migration guidance.
+- If applicable, describe the differences between teaching this to
+  existing roachers and new roachers.
+
+For implementation-oriented RFCs (e.g. for core internals), this
+section should focus on how contributors should think about
+the change, and give examples of its concrete impact. For policy RFCs,
+this section should provide an example-driven introduction to the
+policy, and explain its impact in concrete terms.
+
+# Reference-level explanation
+
+This is the technical portion of the RFC. Explain the design in sufficient detail that:
+
+(You may replace the section title if the intent stays clear.)
+
+- Its interaction with other features is clear.
+- It is reasonably clear how the feature would be implemented.
+- Corner cases are dissected by example.
+
+The section should return to the examples given in the previous
+section, and explain more fully how the detailed proposal makes those
+examples work.
+
+## Detailed design
+
+What / how.
+
+Outline both "how it works" and "what needs to be changed and in which order to get there."
+
+Describe the overview of the design, and then explain each part of the
+implementation in enough detail that reviewers will be able to
+identify any missing pieces. Make sure to call out interactions with
+other active RFCs.
+
+## Drawbacks
+
+Why should we *not* do this?
+
+If applicable, list mitigating factors that may make each drawback acceptable.
+
+## Rationale and Alternatives
+
+This section is extremely important. See the
+[README](README.md##rfc-process) file for details.
+
+- Why is this design the best in the space of possible designs?
+- What other designs have been considered and what is the rationale for not choosing them?
+- What is the impact of not doing this?
+
+## Unresolved questions
+
+- What parts of the design do you expect to resolve through the RFC
+  process before this gets merged?
+- What parts of the design do you expect to resolve through the
+  implementation of this feature before stabilization?
+- What related issues do you consider out of scope for this RFC that
+  could be addressed in the future independently of the solution that
+  comes out of this RFC?
diff --git a/docs/RFCS/schema_gossip.md → docs/RFCS/20150720_schema_gossip.md b/docs/RFCS/schema_gossip.md → docs/RFCS/20150720_schema_gossip.md
diff --git a/docs/RFCS/bounds_generation.md → docs/RFCS/20150729_bounds_generation.md b/docs/RFCS/bounds_generation.md → docs/RFCS/20150729_bounds_generation.md
diff --git a/docs/RFCS/range_replica_naming.md → docs/RFCS/20150729_range_replica_naming.md b/docs/RFCS/range_replica_naming.md → docs/RFCS/20150729_range_replica_naming.md
diff --git a/docs/RFCS/replica_tombstone.md → docs/RFCS/20150729_replica_tombstone.md b/docs/RFCS/replica_tombstone.md → docs/RFCS/20150729_replica_tombstone.md
diff --git a/docs/RFCS/segmented_storage.md → docs/RFCS/20150729_segmented_storage.md b/docs/RFCS/segmented_storage.md → docs/RFCS/20150729_segmented_storage.md
diff --git a/docs/RFCS/local_intent_resolution.md → .../RFCS/20150731_local_intent_resolution.md b/docs/RFCS/local_intent_resolution.md → .../RFCS/20150731_local_intent_resolution.md
diff --git a/docs/RFCS/gateway_batch.md → docs/RFCS/20150806_gateway_batch.md b/docs/RFCS/gateway_batch.md → docs/RFCS/20150806_gateway_batch.md
diff --git a/docs/RFCS/select_from_index.md → docs/RFCS/20150810_select_from_index.md b/docs/RFCS/select_from_index.md → docs/RFCS/20150810_select_from_index.md
diff --git a/docs/RFCS/sql_privileges.md → docs/RFCS/20150810_sql_privileges.md b/docs/RFCS/sql_privileges.md → docs/RFCS/20150810_sql_privileges.md
diff --git a/docs/RFCS/replica_batch.md → docs/RFCS/20150811_replica_batch.md b/docs/RFCS/replica_batch.md → docs/RFCS/20150811_replica_batch.md
diff --git a/docs/RFCS/stateless_replica_relocation.md → .../20150819_stateless_replica_relocation.md b/docs/RFCS/stateless_replica_relocation.md → .../20150819_stateless_replica_relocation.md
diff --git a/docs/RFCS/store_pool.md → docs/RFCS/20150820_store_pool.md b/docs/RFCS/store_pool.md → docs/RFCS/20150820_store_pool.md
diff --git a/docs/RFCS/structured_configs.md → docs/RFCS/20150820_structured_configs.md b/docs/RFCS/structured_configs.md → docs/RFCS/20150820_structured_configs.md
diff --git a/docs/RFCS/table_descriptor_lease.md → docs/RFCS/20151009_table_descriptor_lease.md b/docs/RFCS/table_descriptor_lease.md → docs/RFCS/20151009_table_descriptor_lease.md
diff --git a/docs/RFCS/online_schema_change.md → docs/RFCS/20151014_online_schema_change.md b/docs/RFCS/online_schema_change.md → docs/RFCS/20151014_online_schema_change.md
diff --git a/docs/RFCS/txn_gc.md → docs/RFCS/20151111_txn_gc.md b/docs/RFCS/txn_gc.md → docs/RFCS/20151111_txn_gc.md
diff --git a/docs/RFCS/grpc.md → docs/RFCS/20151207_grpc.md b/docs/RFCS/grpc.md → docs/RFCS/20151207_grpc.md
diff --git a/docs/RFCS/dismantle_multiraft.md → docs/RFCS/20151213_dismantle_multiraft.md b/docs/RFCS/dismantle_multiraft.md → docs/RFCS/20151213_dismantle_multiraft.md
diff --git a/docs/RFCS/sql_column_families.md → docs/RFCS/20151214_sql_column_families.md b/docs/RFCS/sql_column_families.md → docs/RFCS/20151214_sql_column_families.md
diff --git a/docs/RFCS/remove_sql_cli.md → docs/RFCS/20160201_remove_sql_cli.md b/docs/RFCS/remove_sql_cli.md → docs/RFCS/20160201_remove_sql_cli.md
diff --git a/docs/RFCS/typing.md → docs/RFCS/20160203_typing.md b/docs/RFCS/typing.md → docs/RFCS/20160203_typing.md
diff --git a/docs/RFCS/raft_consistency_checker.md → ...RFCS/20160210_raft_consistency_checker.md b/docs/RFCS/raft_consistency_checker.md → ...RFCS/20160210_raft_consistency_checker.md
diff --git a/docs/RFCS/range_leases.md → docs/RFCS/20160210_range_leases.md b/docs/RFCS/range_leases.md → docs/RFCS/20160210_range_leases.md
diff --git a/docs/RFCS/freeze.md → docs/RFCS/20160218_freeze.md b/docs/RFCS/freeze.md → docs/RFCS/20160218_freeze.md
diff --git a/docs/RFCS/index_hints.md → docs/RFCS/20160331_index_hints.md b/docs/RFCS/index_hints.md → docs/RFCS/20160331_index_hints.md
diff --git a/docs/RFCS/dump.md → docs/RFCS/20160418_dump.md b/docs/RFCS/dump.md → docs/RFCS/20160418_dump.md
diff --git a/docs/RFCS/proposer_evaluated_kv.md → docs/RFCS/20160420_proposer_evaluated_kv.md b/docs/RFCS/proposer_evaluated_kv.md → docs/RFCS/20160420_proposer_evaluated_kv.md
diff --git a/docs/RFCS/distributed_sql.md → docs/RFCS/20160421_distributed_sql.md b/docs/RFCS/distributed_sql.md → docs/RFCS/20160421_distributed_sql.md
diff --git a/docs/RFCS/drain_modes.md → docs/RFCS/20160425_drain_modes.md b/docs/RFCS/drain_modes.md → docs/RFCS/20160425_drain_modes.md
diff --git a/docs/RFCS/fk.md → docs/RFCS/20160426_fk.md b/docs/RFCS/fk.md → docs/RFCS/20160426_fk.md
diff --git a/docs/RFCS/upsert.md → docs/RFCS/20160426_upsert.md b/docs/RFCS/upsert.md → docs/RFCS/20160426_upsert.md
diff --git a/docs/RFCS/version_upgrades.md → docs/RFCS/20160426_version_upgrades.md b/docs/RFCS/version_upgrades.md → docs/RFCS/20160426_version_upgrades.md
diff --git a/docs/RFCS/rebalancing_v2.md → docs/RFCS/20160503_rebalancing_v2.md b/docs/RFCS/rebalancing_v2.md → docs/RFCS/20160503_rebalancing_v2.md
diff --git a/docs/RFCS/time_travel.md → docs/RFCS/20160524_time_travel.md b/docs/RFCS/time_travel.md → docs/RFCS/20160524_time_travel.md
diff --git a/docs/RFCS/type_annotations.md → docs/RFCS/20160525_type_annotations.md b/docs/RFCS/type_annotations.md → docs/RFCS/20160525_type_annotations.md
diff --git a/docs/RFCS/sql_interleaved_tables.md → docs/RFCS/20160624_sql_interleaved_tables.md b/docs/RFCS/sql_interleaved_tables.md → docs/RFCS/20160624_sql_interleaved_tables.md
diff --git a/docs/RFCS/expressive_zone_config.md → docs/RFCS/20160706_expressive_zone_config.md b/docs/RFCS/expressive_zone_config.md → docs/RFCS/20160706_expressive_zone_config.md
diff --git a/docs/RFCS/backup_restore.md → docs/RFCS/20160720_backup_restore.md b/docs/RFCS/backup_restore.md → docs/RFCS/20160720_backup_restore.md
diff --git a/docs/RFCS/information_schema.md → docs/RFCS/20160721_information_schema.md b/docs/RFCS/information_schema.md → docs/RFCS/20160721_information_schema.md
diff --git a/docs/RFCS/streaming_snapshots.md → docs/RFCS/20160730_streaming_snapshots.md b/docs/RFCS/streaming_snapshots.md → docs/RFCS/20160730_streaming_snapshots.md
diff --git a/docs/RFCS/quiesce_ranges.md → docs/RFCS/20160824_quiesce_ranges.md b/docs/RFCS/quiesce_ranges.md → docs/RFCS/20160824_quiesce_ranges.md
diff --git a/docs/RFCS/views.md → docs/RFCS/20160830_views.md b/docs/RFCS/views.md → docs/RFCS/20160830_views.md
diff --git a/docs/RFCS/time_series_culling.md → docs/RFCS/20160901_time_series_culling.md b/docs/RFCS/time_series_culling.md → docs/RFCS/20160901_time_series_culling.md
diff --git a/docs/RFCS/time_conversion.md → docs/RFCS/20161006_time_conversion.md b/docs/RFCS/time_conversion.md → docs/RFCS/20161006_time_conversion.md
diff --git a/docs/RFCS/cluster_upgrade_tool.md → docs/RFCS/20161024_cluster_upgrade_tool.md b/docs/RFCS/cluster_upgrade_tool.md → docs/RFCS/20161024_cluster_upgrade_tool.md
diff --git a/docs/RFCS/leaseholder_rebalancing.md → .../RFCS/20161026_leaseholder_rebalancing.md b/docs/RFCS/leaseholder_rebalancing.md → .../RFCS/20161026_leaseholder_rebalancing.md
diff --git a/docs/RFCS/join_filters.md → docs/RFCS/20161215_join_filters.md b/docs/RFCS/join_filters.md → docs/RFCS/20161215_join_filters.md
diff --git a/docs/RFCS/enterprise.md → docs/RFCS/20170117_enterprise.md b/docs/RFCS/enterprise.md → docs/RFCS/20170117_enterprise.md
diff --git a/docs/RFCS/sql_parallelization.md → docs/RFCS/20170124_sql_parallelization.md b/docs/RFCS/sql_parallelization.md → docs/RFCS/20170124_sql_parallelization.md
diff --git a/docs/RFCS/leaseholder_locality.md → docs/RFCS/20170125_leaseholder_locality.md b/docs/RFCS/leaseholder_locality.md → docs/RFCS/20170125_leaseholder_locality.md
diff --git a/docs/RFCS/sql_partitioning.md → docs/RFCS/20170208_sql_partitioning.md b/docs/RFCS/sql_partitioning.md → docs/RFCS/20170208_sql_partitioning.md
diff --git a/docs/RFCS/system_jobs.md → docs/RFCS/20170215_system_jobs.md b/docs/RFCS/system_jobs.md → docs/RFCS/20170215_system_jobs.md
diff --git a/docs/RFCS/sql_split_syntax.md → docs/RFCS/20170314_sql_split_syntax.md b/docs/RFCS/sql_split_syntax.md → docs/RFCS/20170314_sql_split_syntax.md
diff --git a/docs/RFCS/settings_table.md → docs/RFCS/20170317_settings_table.md b/docs/RFCS/settings_table.md → docs/RFCS/20170317_settings_table.md
diff --git a/docs/RFCS/init_command.md → docs/RFCS/20170318_init_command.md b/docs/RFCS/init_command.md → docs/RFCS/20170318_init_command.md
diff --git a/docs/RFCS/certificate_rotation.md → docs/RFCS/20170319_certificate_rotation.md b/docs/RFCS/certificate_rotation.md → docs/RFCS/20170319_certificate_rotation.md
diff --git a/docs/RFCS/postgres_syntax.md → docs/RFCS/20170424_postgres_syntax.md b/docs/RFCS/postgres_syntax.md → docs/RFCS/20170424_postgres_syntax.md
diff --git a/docs/RFCS/monitoring_queries_and_sessions.md → ...170505_monitoring_queries_and_sessions.md b/docs/RFCS/monitoring_queries_and_sessions.md → ...170505_monitoring_queries_and_sessions.md
diff --git a/docs/RFCS/algebraic_data_types.md → docs/RFCS/20170517_algebraic_data_types.md b/docs/RFCS/algebraic_data_types.md → docs/RFCS/20170517_algebraic_data_types.md
diff --git a/docs/RFCS/array_encoding.md → docs/RFCS/20170518_array_encoding.md b/docs/RFCS/array_encoding.md → docs/RFCS/20170518_array_encoding.md
diff --git a/docs/RFCS/external_storage.md → docs/RFCS/20170522_external_storage.md b/docs/RFCS/external_storage.md → docs/RFCS/20170522_external_storage.md
diff --git a/docs/RFCS/pause_resume_cancel.md → docs/RFCS/20170601_pause_resume_cancel.md b/docs/RFCS/pause_resume_cancel.md → docs/RFCS/20170601_pause_resume_cancel.md
diff --git a/docs/RFCS/raft_sstable_sideloading.md → ...RFCS/20170601_raft_sstable_sideloading.md b/docs/RFCS/raft_sstable_sideloading.md → ...RFCS/20170601_raft_sstable_sideloading.md
diff --git a/docs/RFCS/distsql_limit.md → docs/RFCS/20170602_distsql_limit.md b/docs/RFCS/distsql_limit.md → docs/RFCS/20170602_distsql_limit.md
diff --git a/docs/RFCS/rebalancing_for_1_1.md → docs/RFCS/20170602_rebalancing_for_1_1.md b/docs/RFCS/rebalancing_for_1_1.md → docs/RFCS/20170602_rebalancing_for_1_1.md
diff --git a/docs/RFCS/dedicated_raft_storage.md → docs/RFCS/20170605_dedicated_raft_storage.md b/docs/RFCS/dedicated_raft_storage.md → docs/RFCS/20170605_dedicated_raft_storage.md
diff --git a/docs/RFCS/decommission.md → docs/RFCS/20170608_decommission.md b/docs/RFCS/decommission.md → docs/RFCS/20170608_decommission.md
diff --git a/docs/RFCS/query_cancellation.md → docs/RFCS/20170608_query_cancellation.md b/docs/RFCS/query_cancellation.md → docs/RFCS/20170608_query_cancellation.md
diff --git a/docs/RFCS/streaming_results.md → docs/RFCS/20170620_streaming_results.md b/docs/RFCS/streaming_results.md → docs/RFCS/20170620_streaming_results.md
diff --git a/docs/RFCS/web_session_login.md → docs/RFCS/20170628_web_session_login.md b/docs/RFCS/web_session_login.md → docs/RFCS/20170628_web_session_login.md
diff --git a/docs/RFCS/jobs_monitoring.md → docs/RFCS/20170701_jobs_monitoring.md b/docs/RFCS/jobs_monitoring.md → docs/RFCS/20170701_jobs_monitoring.md
diff --git a/docs/RFCS/distsql_buffering_router.md → ...RFCS/20170719_distsql_buffering_router.md b/docs/RFCS/distsql_buffering_router.md → ...RFCS/20170719_distsql_buffering_router.md
diff --git a/docs/RFCS/README.md b/docs/RFCS/README.md
@@ -3,32 +3,71 @@
 This directory contains RFCs (design documents) that describe
 proposed changes to cockroach.
 
-# RFC process
+# Why and when to send a RFC?
 
 Before making major changes, consider sending an RFC for discussion.
 This is a lightweight design-document process that is inspired by the
 [process used by the rust project](https://github.com/rust-lang/rfcs).
 
-1. Copy `template.md` to a new file and fill in the details. Commit
+What is a major change?
+
+A change is "major" and requires a RFC when any of the following
+conditions apply:
+
+- completing the change will cost you more than a week of work.
+- reviewers from more than one team are needed to review the change.
+- users will need to change the way they use CockroachDB as a result.
+- other CockroachDB contributors will need to change the way
+  they work as a result.
+- the architecture of the software or the project changes in a way visible
+  to more than a handful of developers.
+- the change impacts the cost model of CockroachDB (how much time and
+  how much memory is used for common operations) in a way that's
+  noticeable by users.
+
+# RFC process
+
+1. Copy `00000000_template.md` to a new file and fill in the details. Commit
    this version in your own fork of the repository or a branch.
 
-2. Submit a pull request to add your new file to the main repository.
+2. Submit a pull request (PR) to add your new file to the main repository.
    Each RFC should get its own pull request; do not combine RFCs with
    other files.
 
+   Note: you can submit a PR before the RFC is complete, to solicit
+   input about what to write in the RFC. In this case, include the word
+   "WIP" in the PR title and use the label do-not-merge, until
+   you are confident the RFC is complete and can be reviewed.
+
+   **Before you consider the RFC ready to be reviewed, give extra
+   attention to the section "Rationale and Alternatives". It's
+   important for the reviewers to understand why the solution chosen
+   was right. It is an unfortunate fact that often a solution is
+   determined first and the RFC is then written to support that
+   solution, without much consideration being given to the
+   alternatives. You should be mindful of this when it happens and
+   attempt to compensate by a serious review of alternatives.**
+
 3. Go through the PR review. When the dust on the PR review has settled,
    and if there is consensus to proceed with the project, begin the
    final comment period (FCP) by (1) posting a comment on the PR and
    (2) posting an announcement on the persistent public communication
    channel du jour (https://forum.cockroachlabs.com/ at the time of
    this writing).
    The FCP should last a minimum of two working days to allow
-   collaborators to voice any last-minute concerns. If there is still
-   consensus to proceed after the FCP, change the `Status` field of the
-   document to `in-progress`, update the `RFC PR` field, and merge the
-   PR. If the project is rejected, either abandon the PR or merge it
+   collaborators to voice any last-minute concerns.
+
+4. If there is still consensus to proceed after the FCP:
+
+   - change the `Status` field of the document to `in-progress`;
+   - rename the RFC document to prefix it with the current date (`YYYYMMDD_`);
+   - update the `RFC PR` field;
+   - and merge the PR.
+
+   If the project is rejected, either abandon the PR or merge it
    with a status of `rejected` (depending on whether the document and
    discussion are worth preserving for posterity).
+
    Note that it is possible for an RFC to receive discussion after it
    has been approved and its PR merged, e.g. during implementation.
    While this is undesirable and should generally be avoided, such
@@ -54,6 +93,14 @@ During its lifetime an RFC can have the following status:
   accepted (next possible status: in-progress) or that it is DOA (next
   possible status: rejected).
 
+- Rejected
+
+  A RFC receives this status when the PR discussions have concluded
+  the proposal should not be implemented.
+
+  Next possible status: none. If you want to ressucitate an idea, make
+  a new RFC.
+
 - In-progress
 
   A RFC receives this status when the PR discussions have concluded

diff --git a/docs/RFCS/template.md b/docs/RFCS/template.md