Lit RFC Process

The Lit RFC ("request for comment") process is a way for "substantial" changes to Lit to be proposed, discussed, designed, refined, and ultimately reach consensus before being implemented or merged into the Lit core libraries.

Objective

Goals

• Bring increased visibility, community feedback, and deliberation to feature requests
• Allow our community to better observe and participate in the Lit team design processes
• Create more opportunities for community contributions: making and editing RFCs, feedback, implementation, etc.
• Raise the quality of feature requests
• Have a consistent and known process for evaluating feature requests
• Create a public record of change discussions, especially rationale for accepting or rejecting a feature request
• Raise the barrier just a bit to making larger feature requests to help with volume, noise, and quality
• Move large and likely longer-to-be-open feature requests out of issues, helping us maintain a smaller and cleaner issue backlog

What is an RFC?

RFC refers to the IETF's Request For Comments process. An RFC is a document or set of documents that describe a feature in detail, and go through a process of review and approval.

For Lit, RFCs are markdown files in the lit/rfcs repository.

RFCs have a structure as defined in the RFC template, including these metadata and sections:

• Champion(s): The people making and maintaining the proposal. This can change over time.
• Stage: Active, Implemented, Deprecated
• Summary
• Objective (goals and non-goals)
• Motivation (background)
• Detailed Design, including these recommended sections:
  • Implementation Plan
  • Backward Compatibility
  • Testing Plan
  • Performance and Code Size Impact
  • Interoperability
  • Security Impact
  • Documentation Plan
• Downsides
• Alternatives

Accepted RFCs are not a guarantee that a feature will be developed and included in Lit. They are an indication that the team has consensus on a feature and design, and is open to accepting PRs to implement it. Things can change, and new information such as implementation feedback may lead the team to deprecate an RFC.

When to use RFCs

RFCs must be created for new and "substantial" changes. "Substantial" is somewhat subjective, but some clear signs are:

• New packages
• New modules, classes, directives, etc. in an existing package
• Most new public-facing API
• Breaking changes

Changes that do not require an RFC:

• Internal implementation changes
• Bug fixes
• Most dev mode changes: warnings, etc.

These criteria leave a category of small changes and experiments open to debate on whether they deserve or require an RFC. We do not wish to slow down development with too much process, so we will leave this area to the discretion of the core team. We will adjust the criteria for requiring RCFs over time.

Relationship to Lit Labs

The Lit project also has a labs process for pre-production experimentation and feedback. With the assumption that when we create a labs package we usually intend for it to eventually graduate, most labs packages should have (or be part of) an RFC.

RFC Process

Stages

RFCs go through the following stages during their lifetime:

• Proposed When an RFC is proposed in an open pull request and being reviewed and iterated on. This is not a state recorded in the RFC metadata, so all RFC PRs will start with a state of Active.
• Rejected When an RFC is rejected and its PR closed.
• Active When an RFC has been accepted, and its PR merged, but hasn't yet been implemented.
• Implemented When an RFC has been implemented and its feature released.
• Withdrawn When a previously accepted RFC has been rejected or withdrawn due to new information, such as implementation difficulty.
• Deprecated When a previously accepted, and possibly implemented RFC has been superceded by a new RFC.

Before opening an RFC

RFCs involve more work than an issue, both to open one and to review one. Before opening an RFC is it a good idea to get some indication of interest from the Lit core team or strong support from the community.

You may get this indication in several ways, from informal to formal:

• A feature request issue is closed with a request to open an RFC
• A core team member directly invites you to open an RFC from a community or support channel like GitHub Discussions, Slack, or Twitter
• You open a "RRFC" (Requesting Request For Comment) issue in lit/rfcs and get positive feedback

Opening an RFC

1. Fork the lit/rfcs repo
2. Draft the RFC
   1. Add the RFC file to /rfcs in a markdown file named NNNN-_descriptive-name_.md
      1. Note the NNNN is literal. RFCs will not have an assigned RFC number when first opened.
3. Open an RFC pull request
   1. Optionally share the draft on GH discussions or Slack before opening a pull request
   2. Once opened, update the RFC with a link to the RFC PR in the metadata. This allows readers of the RFCs to find the review discussions.

Discussion and Iteration

RFCs must be discussed and reviewed by the relevant maintainers, Lit project leadership, and other stakeholders before being accepted or rejected.

Reviewers

RFCs must be reviewed by Lit project leadership and by project area maintainers. Lit project leadership who can approve RFCs are listed in the lit/rfcs repo's CODEOWNERS file. RFCs must be approved by leadership before moving to active stage and being merged. Area maintainers are sometimes identifiable by who is active on certain projects in the lit/lit monorepo, but the Lit team can add the appropriate people as reviews if it's unclear.

Timeline

Many RFC processes have a prescribed timeline for discussion. We aren't yet sure what timelines for feedback are both most productive and attainable. For the time being we aim to have initial feedback within about 7 days and an accepted or rejected decision within about 30 days.

Acceptance

Once accepted, RFCs are assigned an RFC number and pull requests are updated and merged. This means that all RFCs in lit/rfcs start as active. Rejected RFC pull requests are closed.

RFC Meetings

RFC stakeholders may decide that RFCs need or could benefit from live community discussion. They will be added to the RFC meetings agenda list and discussed at the next opportunity.

Updates and Amendments

After being accepted and moved to the Active stage, RFCs are intended to stay mostly unchanged. The design review and feedback will have taken place in the RFC PR review.

However, it's often the case that designs must be chenged due to implementation feedback. In this case Active RFCs can be updated via additional PRs. Implementation PRs should note when they diverge from an RFC and create a parallel RFC update PR.

Small changes to RFCs can be made to:

• Add clarifications
• Update metadata and other non-design text (examples, documentation)
• Changes to implementation, possibly based on implementor feedback

Major changes proposed to an RFC, such as an alternative to the feature or very different public API and behavior should be done in a new RFC. If a new RFC deprecates a previous RFC, it must mark the previous RFC as deprecated with a link to the new RFC. Otherwise the new RFC should update the previous RFC with a link and callouts to the new RFCs in relevant places.

Implementation

As RFCs are implemented, they should be updated to indicate so. The status is updated to Implemented and relevant PRs linked.

Other RFC Processes

The projects have served as inspiration for our process:

• Ember
• npm
• Fuchsia
• Vue