Design principles + README update

DESIGN_PRINCIPLES.md

@@ -0,0 +1,24 @@
+# Concourse Design Principles
+
+Concourse's goal is to solve automation, once and for all, without becoming part of the problem.
+
+
+## Expressive by being precise
+
+Concourse should provide concepts that build a strong mental model for the user's project, and this model should remain intuitive as the user's automation requirements grow.
+
+Concepts should precisely outline their motivation and intended workflows. Friction and complexity resulting from the imprecise application of a concept should be a cue to introduce new ideas. ([Example](https://blog.concourse-ci.org/reinventing-resource-types/))
+
+
+## Versatile by being universal
+
+Concourse should be able to do a lot with a little. New concepts should only be introduced if their intended workflow cannot be precisely expressed in terms of existing concepts.
+
+Concepts should not be highly specialized for one domain or introduce tight coupling to specific technologies. Users should be able to relate to every concept, and their automation should be insulated from the constant churn of the tech industry.
+
+
+## Safe by being destructible
+
+Concourse should prevent [anti-patterns](https://github.com/concourse/concourse/wiki/Anti-Patterns) and the accumulation of technical debt. Concourse's concepts should make good practices feel intuitive and bad practices feel uncomfortable.
+
+Automation should be self-contained and reproducible in order to maintain business continuity when recovering from disaster scenarios (e.g. total cluster loss). Concourse should merely be a choreographer of mission-critical state kept in an external source of truth, allowing individual installations to be ephemeral.

README.md

@@ -1,132 +1,192 @@
 # Concourse RFCs
 
-A process for collaborating on substantial changes to Concourse.
+The Concourse project uses the RFC (request for comments) process for
+collaborating on substantial changes to Concourse. RFCs enable contributors to
+collaborate during the design process, providing clarity and validation before
+jumping to implementation.
 
 
-## What should be proposed as an RFC?
+## When the RFC process is necessary
 
-RFCs should be opened for changes that have a substantial impact on Concourse
-users and contributors. RFCs enable the community to collaborate during the
-architecture and feature design process, before getting to code and
-implementation.
+The RFC process is necessary for changes which have a substantial impact on end
+users, operators, or contributors. "Substantial" is subjective, but it
+generally includes:
 
-An RFC may not be necessary for changes that are narrow enough in scope with
-limited impact to the rest of Concourse. If you feel that this is the case, you
-can cut straight to submitting a PR, though it's still a good idea to have an
-issue opened first to provide additional context. Do note however that pull
-requests and issues may be closed with a polite request to submit an RFC first.
-
-If you're not sure whether to open an RFC for a change you'd like to propose,
-feel free to discuss beforehand in [Discord](https://discord.gg/MeRxXKW) - just
-ping `@rfc-czars` or guauge interest in `#contributors`.
+* Changes to core workflow functionality (pipelines, tasks, new concepts).
+* Changes to how Concourse is packaged, distributed, or configured.
+* Changes with significant architectural implications (new runtimes, auth
+  schemes, etc.).
+* Changes which modify or introduce officially supported interfaces (HTTP APIs, external integrations, etc).
 
+An RFC is not necessary for changes which have narrow scope and don't leave
+much to be discussed:
 
-## Providing feedback to an RFC
+* Bug fixes and optimizations with no semantic change.
+* Small features which only impact a narrow use case and affect users in an
+  obvious way.
 
-This process is centered around pull requests. Feedback and questions should be
-left as comments on specific lines of the pull request's proposal document, so
-that they can be marked as resolved. This is to avoid an ever-growing sequence
-of comments at the top level.
+The RFC process aims to prevent wasted time and effort on substantial changes
+that end up being sent back to the drawing board. If your change takes minimal
+effort, or if you don't mind potentially scrapping it and starting over, feel
+free to skip this process. Do note however that pull requests may be closed
+with a polite request to submit an RFC.
 
-Top-level comments and pull-request reviews are allowed for overarching
-commentary, but in general line-wise comments are preferred.
+If you're not sure whether to open an RFC for a change you'd like to propose,
+feel free to [ask in `#dev`](https://discord.gg/MeRxXKW)!
 
 
 ## Submitting an RFC
 
 1. Fork this repository.
+
 1. Copy the `000-example` RFC template, naming it something like
+   `000-my-proposal`.
+
+1. Write your proposal in `000-my-proposal/proposal.md`.
+
+    * Consult the [Concourse design principles](DESIGN_PRINCIPLES.md) to guide
+      your design.
+
+    * Include any dependent assets (examples, screenshots) under your RFC
+      directory.
+
+1. Submit a pull request. The pull request number determines the RFC number.
+
+    * Keep the description light; your proposal should contain all relevant
+      information. Feel free to link to any relevant GitHub issues, since that
+      helps with networking.
+
+1. Rename the proposal directory to match the pull request number, e.g.
    `123-my-proposal`.
-    * Don't worry too much about the number; they don't have to be sequential.
-      You can try to predict your pull request number for example, and/or just
-      edit it after submitting.
-1. Write your RFC in `proposal.md` under your RFC directory.
-      * Try to paint a clear mental picture of the motivation for the proposal
-        first. A proposal with no context is more likely to fall under
-        scrutiny.
-      * Having a summary near the beginning of the proposal is also helpful,
-        and if your proposal defines new terms, explicitly listing those
-        up-front is also a good idea.
-      * Take special care to think about any risks, side effects, or drawbacks
-        to your proposal ahead-of-time. These have to be assessed at some
-        point! If you're not sure how to resolve them, leave them under an
-        "open questions" section, and we can all try to work through them
-        together.
-1. Submit a pull request. Your proposal may include any dependent assets
-   (example content, screenshots) under its RFC directory. For convenience,
-   link to the rendered proposal in the pull request body, like so:
+
+   For convenience, update the PR description to link to the rendered proposal
+   in the pull request body like so:
 
    ```
    [Rendered](https://github.com/{YOUR NAME}/rfcs/blob/{YOUR BRANCH}/123-my-proposal/proposal.md)
    ```
 
-   Try to keep the description light, since most content should be in the
-   `proposal.md` already. But feel free to reference any relevant GitHub
-   issues, since that helps with context-building.
-1. Each RFC will be assigned to at least one reviewer. Feel free to reach out
-   to them if you need help on any part of the process or with the proposal
-   itself.
-1. Community members are expected to submit feedback by leaving comments on
-   lines in the pull request and submitting reviews. This allows conversations
-   to be marked "resolved" and prevents the comment history on the pull request
-   from growing larger and larger.
-    * As the RFC author, feel free to leave your own comments/feedback, using
-      the pull request as a "captain's log" as you think about the problem more
-      and reach key decisions. The point of all this is to have a clear public
-      record for the decision-making process.
-1. Amendments to the RFC should be made by pushing more commits to the RFC
-   branch. **Please do not rebase and force-push over your own commits.**
-   Instead, try to make meaningful commits that summarize their changes.
+1. Feel free to review your own RFC and leave comments and questions as you
+   reason about the problem and reach key decisions. Doing so helps build a
+   public record of the decision-making process.
+
+1. The RFC will be assigned to a member of the [**core** team][core-team]. The
+   assignee is responsible for providing feedback and eventually shepherding
+   the RFC through the [resolution process](#resolution). Reach out to your
+   RFC's assignee if you need any help with the RFC process.
+
+1. Collect user feedback and votes (GitHub reactions) for your own RFC by
+   linking to it in issues or contexts where it is relevant. Please be
+   respectful of other RFC authors and avoid vote brigading; diversity of
+   perspective is more important than having the most votes.
+
+   The [Concourse website](https://concourse-ci.org) lists open RFCs ranked by
+   GitHub reactions in order to increase exposure to end users. The goal of
+   ranking them is to focus attention on the RFCs most relevant to the
+   community, increasing clarity through user feedback and accelerating them to
+   resolution.
+
+1. Amend your proposal in response to feedback by pushing more commits to your
+   fork. Whenever possible, please make meaningful commits that summarize the
+   changes and reasoning (rather than rebasing and force-pushing all the time).
+
+
+## Reviewing RFCs
+
+Concourse users and contributors are encouraged to review RFCs alongside
+members of the core team. Feedback from diverse perspectives is necessary for
+determining a proposal's efficacy, impact, and priority. Reviewing RFCs is also
+great practice for [joining the core team][joining-a-team] someday!
+
+Reviewers should focus on resolving open questions, surfacing risks and
+drawbacks, and providing constructive critique of the overall approach. The
+[Concourse design principles](DESIGN_PRINCIPLES.md) serve as a guiding hand to
+determine the proposal's alignment with the Concourse philosophy.
+
+Reviewers should leave questions and comments on individual lines via PR review
+so that discussions may be threaded and marked as resolved. Leaving GitHub
+reactions also helps to measure consensus without cluttering the comment thread
+if you don't have much more to add.
 
 
 ### Resolution
 
-Once consensus builds and things slow down, the RFC will be granted with one of
-the following labels:
+The review process should lead to consensus from three different perspectives:
 
-* `resolution/merge`: there are no outstanding objections to the RFC and
-  implementation can begin as soon as the RFC is merged.
-* `resolution/postpone`: there are no outstanding objections to the RFC, but we
-  have decided to defer its implementation until some time in the future, and
-  until then it's better to leave the proposal unmerged in case things change
-  by the time we can get to implementation.
-* `resolution/close`: we have decided not to accept the RFC, and have no plans
-  for implementation.
+* Members of the **core** team have determined whether the proposal fits with
+  the Concourse design principles and whether the changes sufficiently improve
+  the product.
+* The **maintainers** have determined whether the proposal is worth
+  maintaining, i.e. whether the benefits of the proposal outweigh any technical
+  tradeoffs, or if it introduces an unsustainable maintenance burden.
+* Enough community input has been provided to validate the need and efficacy of
+  the proposal.
 
-These labels mark the beginning of the final phase of the RFC. During this
-point, any additional feedback will be sought out by communicating it on our
-[blog](https://blog.concourse-ci.org).
+Once the review status stabilizes and clarity has been reached, the core team
+assignee will grant the RFC one of the following labels:
 
-There will then be a two-week quiet period on the RFC. If during this time
-there is a challenge to the resolution, the label will be removed and the RFC
-process will continue. Ideally there are no changes to the RFC during this
-period (all typos should be resolved by now, and wording should be fairly
-clear).
+* **resolution/merge**: the proposal will be merged; there are no outstanding
+  objections, and implementation can begin as soon as the RFC is merged.
+* **resolution/close**: the proposal will be closed.
+* **resolution/postpone**: resolution will be deferred until a later time when
+  the motivating factors may have changed.
 
-Depending on the resolution, the following will happen to the RFC pull request:
+These labels initiate a two-week quiet period, and any final feedback will be
+sought by bumping the RFC to the top of the RFC table on the Concourse website.
+No further changes should be made to the proposal during this period.
 
-* `resolution/merge`: the PR will be merged!
-* `resolution/postpone`: the PR will be closed and stamped with a `postponed`
-  label. At some point in the future the pull request may be re-opened.
-* `resolution/close`: the PR will be closed with no additional label.
+If there is a challenge to the resolution during the quiet period the label may
+be removed at the discretion of the assignee, and the RFC process will continue
+as before.
 
 
 ## Implementing an RFC
 
-Once an RFC is accepted, an associated issue will be opened on the [`concourse`
-repository](https://github.com/concourse/concourse) repository, referencing the
-RFC's pull request. This issue can be created by the RFC author or assignee.
+When an RFC is merged the core team assignee is responsible for opening an
+issue on the [Concourse repository](https://github.com/concourse/concourse) to
+keep track of its implementation. The issue can be lightweight and just
+reference the RFC. The assignee must also add a link to the issue at the top of
+the RFC's proposal document.
+
+The [**maintainers** team][maintainers-team] is responsible for determining the
+proposal's priority by adding a **priority/high**, **priority/medium**, or
+**priority/low** label to the RFC's issue. Priority is an approximation of
+overall value and desired timeline for implementation.
 
-By the time an RFC is merged, we should have a pretty good idea of who's going
-to implement it. This may or may not be the same person that submitted the RFC.
-Large-scale proposals for example may be picked up by the core Concourse team
-instead (but obviously that'd be something we agree on prior to merging).
+An RFC author is not necessarily responsible for its implementation, though
+they may volunteer. If the maintainers have sufficient bandwidth they may place
+it on their roadmap by prioritizing the issue in a GitHub project. Otherwise
+the maintainers will add a **help wanted** label to the issue.
 
-The implementation process itself falls under the normal [Concourse development
-process](https://github.com/concourse/concourse/blob/master/CONTRIBUTING.md).
+In any case, contributors may volunteer to implement a proposal provided that
+work has not already begun. If you would like to volunteer, please leave a
+comment on the issue to let others know!
+
+From there, the implementation process falls under the normal [Concourse
+development process][contributing].
+
+
+## Revising an RFC
+
+RFCs represent the planning phase. An RFC's proposal is not the source of truth
+for the feature's documentation, and should not be revised to keep up with
+later iterations after the initial proposal is implemented. A new RFC should be
+proposed for subsequent changes instead.
+
+If an RFC is merged and later changes are deemed necessary prior to final (i.e.
+non-experimental) implementation, a follow-up PR may be submitted that updates
+the proposal in-place. In this case the RFC author must include a MAJOR.MINOR
+revision number in the proposal and maintain a brief summary of changes at the
+bottom of the proposal.
 
 
 ## License
 
 All RFCs, and any accompanying code and example content, will fall under the
 Apache v2 license present at the root of this repository.
+
+
+[joining-a-team]: https://github.com/concourse/governance#joining-a-team
+[core-team]: https://github.com/concourse/governance/blob/master/teams/core.yml
+[maintainers-team]: https://github.com/concourse/governance/blob/master/teams/maintainers.yml
+[contributing]: https://github.com/concourse/concourse/blob/master/CONTRIBUTING.md