Revert "Remove RFCs from our repository."

This reverts commit e97e3fb.

rfcs/0000_template.md

@@ -0,0 +1,108 @@
+- Start Date: (fill me in with today's date, YYYY-MM-DD)
+- TTL: (e.g. "April 20th, 2021", time the review is expected to be completed by. Don't use relative days.)
+- Champion: (usually you, person who writes and updates the draft and incorporates feedback)
+- Main reviewer: (somebody familiar with the subject matter, who has committed to provide timely and detailed reviews for this RFC)
+- Owner team: (team who will own implementation, if it is accepted)
+- Stakeholders: (people or groups who will be affected by the proposed changes)
+- RFC PR: (leave this empty, it will be a link to PR of this RFC)
+- PoC PR: (optional, link to a PoC implementation of the feature)
+- Kibana Issue: (link to issue where the proposed feature is tracked)
+
+
+# Executive Summary
+
+Summarize this RFC so those unfamiliar with the project and code can quickly understand
+what the problem is, why it is important,
+and the proposed solution. Below are some suggested sections for the Executive
+Summary. Tweak as you desire and try to keep it succinct.
+
+## Problem statement
+
+What is the problem we are trying to solve? Supply any relevant background
+context. Why is this something we should focus on _now_.
+
+Focus on explaining the problem so that if this RFC is not accepted, this
+information could be used to develop alternative solutions. In other words,
+don't couple this too closely with the solution you have in mind.
+
+## Goals
+
+What are the goals of this project? How will we know if it was successful?
+
+## Proposal
+
+What are we doing to achieve the goals and solve the problem?
+
+
+# Who is affected and how
+
+Use this section to hone in on who will be affected and how. For example:
+
+- Are consumers of a specific plugin affected because of a public API change?
+- Will all Kibana Contributors be affected because of a change that may affect
+  the development experience?
+
+
+# Detailed design
+
+This is the bulk of the RFC. Explain the design in enough detail for somebody
+familiar with Kibana 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.
+
+Include architectural diagrams if you see fit, a picture is worth a thousand
+words.
+
+## Terminology
+
+A glossary of new terms can be very helpful.
+
+
+# Risks
+
+Why should we *not* do this? Please consider:
+
+- implementation cost, both in term of code size and complexity
+- the impact on teaching people Kibana development
+- integration of this feature with other existing and planned features
+- cost of migrating existing Kibana plugins (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 Kibana developers adopt it? Is
+this a breaking change? Can we write a codemod? Should we coordinate with
+other projects or libraries?
+
+
+# How this scales
+
+Does this change affect Kibana's performance in a substantial way? Have we discovered
+the upper bounds before we see performance degradations? Will any load 
+tests be added to cover these scenarios?
+
+
+# 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 Kibana patterns?
+
+Would the acceptance of this proposal mean the Kibana documentation must be
+re-organized or altered? Does it change how Kibana is taught to new developers
+at any level?
+
+How should this feature be taught to existing Kibana developers?
+
+
+# Unresolved questions
+
+Optional, but suggested for first drafts. What parts of the design are still
+TBD?

rfcs/README.md

@@ -0,0 +1,139 @@
+# Kibana RFCs
+
+Many changes, including small to medium features, 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 relevant
+Kibana team.
+
+The "RFC" (request for comments) process is intended to provide a
+consistent and controlled path for new features to enter the project.
+
+[Active RFC List](https://github.com/elastic/kibana/pulls?q=is%3Aopen+is%3Apr+label%3ARFC)
+
+Kibana is still **actively developing** this process, and it will still change as
+more features are implemented and the community settles on specific approaches
+to feature development.
+
+## Contributor License Agreement (CLA)
+
+In order to accept your pull request, we need you to submit a CLA. You only need
+to do this once, so if you've done this for another Elastic open source
+project, you're good to go.
+
+**[Complete your CLA here.](https://www.elastic.co/contributor-agreement)**
+
+## When to follow this process
+
+You should consider using this process if you intend to make "substantial"
+changes to Kibana or its documentation. Some examples that would benefit
+from an RFC are:
+
+   - A new feature that creates new API surface area, such as a new
+     service available to plugins.
+   - The removal of features that already shipped as part of a release.
+   - The introduction of new idiomatic usage or conventions, even if they
+     do not include code changes to Kibana itself.
+
+The RFC process is a great opportunity to get more eyeballs on your proposal
+before it becomes a part of a released version of Kibana. Quite often, even
+proposals that seem "obvious" can be significantly improved once a wider
+group of interested people have a chance to weigh in.
+
+The RFC process can also be helpful to encourage discussions about a proposed
+feature as it is being designed, and incorporate important constraints into
+the design while it's easier to change, before the design has been fully
+implemented.
+
+Some changes do not require an RFC:
+
+  - Rephrasing, reorganizing or refactoring
+  - Addition or removal of warnings
+  - Additions that strictly improve objective, numerical quality
+  criteria (speedup, better browser support)
+  - Addition of features that do not impact other Kibana plugins (do not
+  expose any API to other plugins)
+
+## What the process is
+
+In short, to get a major feature added to the Kibana codebase, one usually
+first gets the RFC merged into the RFC tree as a markdown file. At that point
+the RFC is 'active' and may be implemented with the goal of eventual inclusion
+into Kibana.
+
+* Fork the Kibana repo http://github.com/elastic/kibana
+* Copy `rfcs/0000_template.md` to `rfcs/text/0001_my_feature.md` (where
+'my_feature' is descriptive. Assign a number. Check that an RFC with this
+number doesn't already exist in `master` or an open PR).
+* Fill in the RFC. Put care into the details: **RFCs that do not
+present convincing motivation, demonstrate understanding of the
+impact of the design, or are disingenuous about the drawbacks or
+alternatives tend to be poorly-received**.
+* Submit a pull request. As a pull request the RFC will receive design
+feedback from the larger community and Elastic staff. The author should
+be prepared to revise it in response.
+* 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.
+* Eventually, the team will decide whether the RFC is a candidate
+for inclusion in Kibana.
+* RFCs that are candidates for inclusion in Kibana will enter a "final comment
+period" lasting at least 3 working days. The beginning of this period will be signaled with a
+comment and tag on the RFCs pull request.
+* An RFC can be modified based upon feedback from the team and community.
+Significant modifications may trigger a new final comment period.
+* 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 comment period. A team
+member will merge the RFCs associated pull request, at which point the RFC will
+become 'active'.
+
+## The RFC life-cycle
+
+Once an RFC becomes active, then authors may implement it and submit the
+feature as a pull request to the Kibana repo. Becoming 'active' is not a rubber
+stamp, and in particular still does not mean the feature will ultimately
+be merged; it does mean that the team in ownership of the feature has agreed to
+it in principle and are amenable to merging it.
+
+Furthermore, the fact that a given RFC has been accepted and is
+'active' implies nothing about what priority is assigned to its
+implementation, nor whether anybody is currently working on it.
+
+Modifications to active RFCs can be done in followup PRs. We strive
+to write each RFC in a manner that it will reflect the final design of
+the feature; but the nature of the process means that we cannot expect
+every merged RFC to actually reflect what the end result will be at
+the time of the next major release; therefore we try to keep each RFC
+document somewhat in sync with the Kibana feature as planned,
+tracking such changes via followup pull requests to the document. You
+may include updates to the RFC in the same PR that makes the code change.
+
+## Implementing an RFC
+
+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).
+
+## Reviewing RFCs
+
+Each week the team will attempt to review some set of open RFC
+pull requests.
+
+Every accepted feature should have a champion from the team which will
+ultimately maintain the feature long-term. The champion will represent the
+feature and its progress.
+
+**Kibana's RFC process owes its inspiration to the [React RFC process], [Yarn RFC process], [Rust RFC process], and [Ember RFC process]**
+
+[React RFC process]: https://github.com/reactjs/rfcs
+[Yarn RFC process]: https://github.com/yarnpkg/rfcs
+[Rust RFC process]: https://github.com/rust-lang/rfcs
+[Ember RFC process]: https://github.com/emberjs/rfcs

rfcs/text/0001_lifecycle_setup.md

@@ -0,0 +1,141 @@
+- Start Date: 2019-03-05
+- RFC PR: [#32507](https://github.com/elastic/kibana/pull/32507)
+- Kibana Issue: [#33045](https://github.com/elastic/kibana/issues/33045)
+
+# Summary
+
+The `setup` lifecycle function for core and plugins will be for one-time setup
+and configuration logic that should be completed in a finite amount of time
+rather than be available throughout the runtime of the service.
+
+The existing `start` lifecycle function will continue to serve only the purpose
+of longer running code that intentionally only executes when `setup` is
+finished.
+
+# Basic example
+
+```ts
+class Plugin {
+  public setup(core, plugins) {
+    // example operation that should only happen during setup
+    core.savedObjects.setRepository(/* ... */);
+  }
+
+  public start(core, plugins) {
+    // example retrieval of client with guarantee that repository was set above
+    core.savedObjects.getClient();
+  }
+
+  public stop(core, plugins) {
+    // ...
+  }
+}
+```
+
+# Motivation
+
+We want services and plugins to be designed to adapt to changes in data and
+configurations over time, but there are practical limits to this philosophy,
+which we already acknowledge by having a separate `start` and `stop` handler.
+
+Currently, the `start` handler is where the vast majority of business logic
+takes place because it gets fired off almost immediately on startup and then no
+new lifecycle events are encountered until it's time to shutdown.
+
+This results in lifecycle-like behaviors being hardcoded into the `start`
+handler itself rather than being exposed in a systematic way that other
+services and plugins can take advantage of.
+
+For example, core should not bind to a port until all HTTP handlers have been
+registered, but the service itself needs to initialize before it can expose the
+means of registering HTTP endpoints for plugins. It exposes this capability via
+its `start` handler. Port binding, however, is hardcoded to happen after the
+rest of the services are started. No other services behave this way.
+
+Unlike core services which can have hacky hardcoded behaviors that don't
+completely adhere to the order of execution in a lifecycle, plugins have no way
+of saying "execute this only when all plugins have initialized". It's not
+practical for a plugin that has side effects like pushing cluster privileges to
+Elasticsearch to constantly be executing those side effects whenever an
+observable changes. Instead, they need a point in time when they can safely
+assume the necessary configurations have been made.
+
+A `setup` lifecycle handler would allow core and plugins to expose contracts
+that have a reliable expiration in the context of the overall lifecycle.
+
+# Detailed design
+
+A new `setup` lifecycle handler will be adopted for services and plugins. The
+order in which lifecycle handlers execute will be:
+
+1. `setup`
+2. `start`
+3. `stop`
+
+## Core
+
+The core system will have an `setup` function that will get executed prior to
+`start`. An `setup` function will also be added to all core services, and will
+be invoked from the core `setup` in the same spirit of `start` and `stop`.
+
+Decisions on which service functionality should belong in `setup` vs `start`
+will need to be handled case-by-case and is beyond the scope of this RFC, but
+much of the existing functionality will likely be exposed through `setup`
+instead.
+
+## Plugins
+
+Plugins will have an `setup` function that will get executed by the core plugin
+service from its own `setup`.
+
+Like `start` and `stop`, the `setup` lifecycle handler will receive
+setup-specific core contracts via the first argument.
+
+Also like `start` and `stop`, the `setup` lifecycle handler will receive the
+setup-specific plugin contracts from all plugins that it has a declared
+dependency on via the second argument.
+
+# Drawbacks
+
+- An additional lifecycle handler adds complexity for many plugins and services
+which draw no direct benefit from it.
+- The answer to "does this belong in `setup` or `start`?" is not always clear.
+There is not a formal decision tree we can apply to all circumstances.
+- While lifecycle hooks are relatively new, there still many services that will
+need to be updated.
+- Adopting new lifecycle hooks is a slippery slope, and the more we have in the
+system, the more complicated it is to reason about the capabilities of the
+system at any given point.
+
+# Alternatives
+
+When a service or plugin needs to know when initialization has finished, it can
+expose a custom event or transaction system via its relevant contracts so it
+can tell when downstream code has finished initializing. One significant
+drawback to this approach is that it only works when the plugin that needs to
+wait for initialization isn't dependent on an upstream service that does not
+implement a similar transaction capability.
+
+# Adoption strategy
+
+Adoption will need to be manual. Since the bulk of the `start` logic in the
+repo today is configuration-oriented, I recommend renaming `start`->`setup` in
+all services and plugins, and then adding an empty `start` where it is
+necessary. Functionality can then be moved from `setup`->`start` on a
+case-by-case.
+
+If this change doesn't happen for a while, then it might make sense to follow
+the reverse process to ensure the least impact.
+
+The migration guide will be updated to reflect the `setup` and `start`
+distinction as soon as this RFC is accepted.
+
+# How we teach this
+
+There shouldn't need to be much knowledge sharing around this since even
+`start` and `stop` are new concepts to most people. The sooner we introduce
+this change, the better.
+
+# Unresolved questions
+
+None, at the moment.