From 6fc39bc6b5fa269264cdf572ad00dfcb1cb40d76 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Thu, 21 Jul 2022 12:13:16 +0200 Subject: [PATCH] Initial commit --- 0000-template.md | 34 ++++++++++++++++++++++++ README.md | 8 ++++++ text/0001-workflow.md | 60 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 102 insertions(+) create mode 100644 0000-template.md create mode 100644 README.md create mode 100644 text/0001-workflow.md diff --git a/0000-template.md b/0000-template.md new file mode 100644 index 00000000..f7ab1682 --- /dev/null +++ b/0000-template.md @@ -0,0 +1,34 @@ +* Start Date: YYYY-MM-DD +* RFC Type: see below +* RFC PR: + +# Summary + +One paragraph explanation of the feature or document purpose. + +# Motivation + +Why are we doing this? What use cases does it support? What is the expected outcome? + +# Background + +The reason this decision or document is required. This section might not always exist. + +# Supporting Data + +[Metrics to help support your decision (if applicable).] + +# Options Considered + +If an RFC does not know yet what the options are, it can propose multiple options. The +preferred model is to propose one option and to provide alternatives. + +# Drawbacks + +Why should we not do this? What are the drawbacks of this RFC or a particular option if +multiple options are presented. + +# Unresolved questions + +* What parts of the design do you expect to resolve through this RFC? +* What issues are out of scope for this RFC but are known? diff --git a/README.md b/README.md new file mode 100644 index 00000000..928026a7 --- /dev/null +++ b/README.md @@ -0,0 +1,8 @@ +# RFCs + +This repository is supposed to contain RFCs and DACIs. This so far is an experiment and we have not yet committed to it. +For creating a new RFC see [workflow](text/0001-workflow.md). + +## Index + +* [0001-workflow](text/0001-workflow.md): the workflow RFC diff --git a/text/0001-workflow.md b/text/0001-workflow.md new file mode 100644 index 00000000..2db99470 --- /dev/null +++ b/text/0001-workflow.md @@ -0,0 +1,60 @@ +* Start Date: 2022-07-21 +* RFC Type: informational +* RFC PR: - +* RFC Status: - + +# Summary + +This RFC describes the Sentry RFC process. + +# Motivation + +This document exists so that future RFC creators and editors have a workflow to go by. This workflow is inspired by +common RFC processes from the Open Source community (Rust RFCs, Python PEPs) but also our internal use of DACIs. + +# RFC Type + +The are three kinds of RFCs: + +* a **feature** RFC is a RFC describing a new feature to Sentry, an SDK, the protocol or something else that requires a decision to be made. +* a **decision** RFC is a DACI style RFC that tries to capture a contended decision that requires circulation. +* an **informational** RFC is an RFC that provides guideslines, describes an issue or states a longer term plan that does not directly turn into implementation. + +# RFC Status + +* `draft`: this RFC is currently in draft state. +* `active`: this RFC is currently active which means that the content of the document reference the current state of affairs and are supposed to be followed. + This status is used for RFCs that are informational or general guides. +* `approved`: the approver of an RFC approved the decision. +* `withdrawn`: the RFC was withdrawn. Typically such RFCs are not visible in the repository as the corresponding PRs are not merged unless they are withdrawn after accepted. +* `replaced`: the RFC was later replaced by another RFC. + +# RFC Creation Workflow + +1. Create a new RFC document as a copy of `0000-template.md`. +2. Name it `XXXX-short-description.md` and commit it to a new branch. +3. Create a pull request against the `rfcs` repository. The number of the pull request then + becomes the assigned RFC number filled into `XXXX`. Zero pad it out to 4 places for better sorting. +4. Pick an RFC type and write it down on your RFC text into the header. + +If you are writing a DACI style RFC, read "Instructions for running this Play" (10 mins) from +[Atlassian's Playbook](https://www.atlassian.com/team-playbook/plays/daci). Mention informed and contributors in the PR +description and assign the approver to the PR. + +Comments are to be left on the text for suggestions and in the general GitHub pull request comment system. + +# RFC Approval Process + +Once the approver (can be a person or a TSC) approved the RFC it gets merged. At that point these things have to happen: + +1. Ensure that the RFC PR link is filled in. +2. Ensure that the document is named after the PR number if it hasn't yet. +3. Ensure the RFC is merged and hows up in `text`. +4. Ensure that a link to the `README.md` file is added for the RFC. + +# RFC Withdrawing + +RFCs do not need to complete. The creator can always withdraw (status `withdrawn`) the RFC at which point the PR is closed. It can be reopened later. + +RFCs that are `active` can be retried by setting the status to `replaced` or `withdrawn`. The former is to be used if another RFC has since replaced it. +Rather than doing that, it's typically better to edit and update the RFC instead (eg: informational RFCs are living documents).