Skip to content

Commit ea1dc86

Browse files
justinfagnanijustinfagnani
authored
Redo initial RFC process commit (#2)
1 parent 4109c9a commit ea1dc86

File tree

4 files changed

+361
-2
lines changed

4 files changed

+361
-2
lines changed

‎CODEOWNERS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# These are the approvers for Lit RFCs
2+
* @graynorton @justinfagnani @kevinpschaaf @sorvell

‎README.md‎

Lines changed: 143 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,143 @@
1-
# rfcs
2-
RFCs for changes to Lit
1+
# Lit RFC Process
2+
3+
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.
4+
5+
## Objective
6+
7+
### Goals
8+
9+
* Bring increased visibility, community feedback, and deliberation to feature requests
10+
* Allow our community to better observe and participate in the Lit team design processes
11+
* Create more opportunities for community contributions: making and editing RFCs, feedback, implementation, etc.
12+
* Raise the quality of feature requests
13+
* Have a consistent and known process for evaluating feature requests
14+
* Create a public record of change discussions, especially rationale for accepting or rejecting a feature request
15+
* Raise the barrier _just a bit_ to making larger feature requests to help with volume, noise, and quality
16+
* Move large and likely longer-to-be-open feature requests out of issues, helping us maintain a smaller and cleaner issue backlog
17+
18+
## What is an RFC?
19+
20+
RFC refers to the IETF's [Request For Comments](https://en.wikipedia.org/wiki/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.
21+
22+
For Lit, RFCs are markdown files in the lit/rfcs repository.
23+
24+
RFCs have a structure as defined in the [RFC template](./rfcs/0000-rfc-template.md), including these metadata and sections:
25+
26+
* Champion(s): The people making and maintaining the proposal. This can change over time.
27+
* Stage: Active, Implemented, Deprecated
28+
* Summary
29+
* Objective (goals and non-goals)
30+
* Motivation (background)
31+
* Detailed Design, including these recommended sections:
32+
* Implementation Plan
33+
* Backward Compatibility
34+
* Testing Plan
35+
* Performance and Code Size Impact
36+
* Interoperability
37+
* Security Impact
38+
* Documentation Plan
39+
* Downsides
40+
* Alternatives
41+
42+
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.
43+
44+
## When to use RFCs
45+
46+
RFCs must be created for new and "substantial" changes. "Substantial" is somewhat subjective, but some clear signs are:
47+
48+
* New packages
49+
* New modules, classes, directives, etc. in an existing package
50+
* Most new public-facing API
51+
* Breaking changes
52+
53+
Changes that do _not_ require an RFC:
54+
55+
* Internal implementation changes
56+
* Bug fixes
57+
* Most dev mode changes: warnings, etc.
58+
59+
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.
60+
61+
#### Relationship to Lit Labs
62+
63+
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.
64+
65+
## RFC Process
66+
67+
### Stages
68+
69+
RFCs go through the following stages during their lifetime:
70+
71+
* **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`.
72+
* **Rejected** When an RFC is rejected and its PR closed.
73+
* **Active** When an RFC has been accepted, and its PR merged, but hasn't yet been implemented.
74+
* **Implemented** When an RFC has been implemented and its feature released.
75+
* **Withdrawn** When a *previously accepted* RFC has been rejected or withdrawn due to new information, such as implementation difficulty.
76+
* **Deprecated** When a *previously accepted*, and possibly implemented RFC has been superceded by a new RFC.
77+
78+
### Before opening an RFC
79+
80+
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.
81+
82+
You may get this indication in several ways, from informal to formal:
83+
84+
* A feature request issue is closed with a request to open an RFC
85+
* A core team member directly invites you to open an RFC from a community or support channel like GitHub Discussions, Slack, or Twitter
86+
* You open a "[RRFC](https://github.com/lit/rfcs/issues/new)" (Requesting Request For Comment) issue in lit/rfcs and get positive feedback
87+
88+
### Opening an RFC
89+
90+
1. Fork the lit/rfcs repo
91+
2. Draft the RFC
92+
1. Add the RFC file to /rfcs in a markdown file named `NNNN-_descriptive-name_.md`
93+
1. Note the `NNNN` is literal. RFCs will not have an assigned RFC number when first opened.
94+
3. Open an RFC pull request
95+
1. Optionally share the draft on [GH discussions](https://github.com/lit/lit/discussions) or [Slack](https://lit.dev/slack-invite/) before opening a pull request
96+
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.
97+
98+
### Discussion and Iteration
99+
100+
RFCs must be discussed and reviewed by the relevant maintainers, Lit project leadership, and other stakeholders before being accepted or rejected.
101+
102+
#### Reviewers
103+
104+
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](./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.
105+
106+
#### Timeline
107+
108+
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.
109+
110+
#### Acceptance
111+
112+
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.
113+
114+
#### RFC Meetings
115+
116+
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.
117+
118+
### Updates and Amendments
119+
120+
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.
121+
122+
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.
123+
124+
Small changes to RFCs can be made to:
125+
126+
* Add clarifications
127+
* Update metadata and other non-design text (examples, documentation)
128+
* Changes to implementation, possibly based on implementor feedback
129+
130+
_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.
131+
132+
### Implementation
133+
134+
As RFCs are implemented, they should be updated to indicate so. The status is updated to *Implemented* and relevant PRs linked.
135+
136+
## Other RFC Processes
137+
138+
The projects have served as inspiration for our process:
139+
140+
* [Ember](https://github.com/emberjs/rfcs)
141+
* [npm](https://github.com/npm/rfcs)
142+
* [Fuchsia](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/contribute/governance/rfcs/rfc_process.md)
143+
* [Vue](https://github.com/vuejs/rfcs)

‎rfcs/0000-rfc-template.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
Status: Active
3+
Champions: {{ your_github_username }}
4+
PR: {{ update_with_pr_number }}
5+
---
6+
7+
# {{ TITLE }}
8+
9+
Brief summary paragraph describing the RFC.
10+
11+
## Objective
12+
13+
What is the RFC trying to accomplish?
14+
15+
### Goals
16+
- Specific goals of the RFC
17+
18+
### Non-Goals
19+
- Specific non-goals of the RFC
20+
21+
## Motivation
22+
23+
Why is the RFC neccessary? What background information is needed to understand why?
24+
25+
## Detailed Design
26+
27+
Describe the change in detail. Include API changes and usage examples. Add your own sub-headings as necessary.
28+
29+
## Implementation Considerations
30+
31+
### Implementation Plan
32+
33+
Is there anything important to note about implementation plan? Can it be done in a single PR or will it need to be staged out across several?
34+
35+
### Backward Compatibility
36+
37+
Backwards compatibility is extremely important to Lit, especially in the core libraries. Does this proposal break backwards compatibility? Are there workarounds?
38+
39+
### Testing Plan
40+
41+
How will this proposal be tested? Are unit tests sufficient, or do we need integration tests? Is any unique testing infrastructure required?
42+
43+
### Performance and Code Size Impact
44+
45+
What impact will this proposal have on performance and code size? What benchmarks should we create to evaluate the proposal?
46+
47+
### Interoperability
48+
49+
Is this proposal for a feature that could be interoperable across web components not written in Lit? Does it create a tight coupling between components written in Lit? Could it be a [Web Components Community Group](https://github.com/w3c/webcomponents-cg) [Community Protocol](https://github.com/webcomponents-cg/community-protocols)?
50+
51+
### Security Impact
52+
53+
What impact will this proposal have on security? Does the proposal require a security review? (We have a security team available for reviews)
54+
55+
We especially care about the handling of untrusted user input by library code so that we contnue to prevent XSS vectors.
56+
57+
### Documentation Plan
58+
59+
Do we need to create or update any documentation to complete this proposal? Does related documentation have a clear home in our docs outline? What playground examples or tutorials should be created?
60+
61+
## Downsides
62+
63+
Many proposals involve trade-offs. What are they for this proposal and what are the downsides of this approach?
64+
65+
## Alternatives
66+
67+
What alternatives were considered and rejected? Why?

‎rfcs/0001-rfc-process.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
Status: Accepted
3+
Champions: @justinfagnani
4+
PR:
5+
---
6+
7+
# Lit RFC Process
8+
9+
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.
10+
11+
## Objective
12+
13+
### Goals
14+
15+
* Bring increased visibility, community feedback, and deliberation to feature requests
16+
* Allow our community to better observe and participate in the Lit team design processes
17+
* Create more opportunities for community contributions: making and editing RFCs, feedback, implementation, etc.
18+
* Raise the quality of feature requests
19+
* Have a consistent and known process for evaluating feature requests
20+
* Create a public record of change discussions, especially rationale for accepting or rejecting a feature request
21+
* Raise the barrier _just a bit_ to making larger feature requests to help with volume, noise, and quality
22+
* Move large and likely longer-to-be-open feature requests out of issues, helping us maintain a smaller and cleaner issue backlog
23+
24+
## What is an RFC?
25+
26+
RFC refers to the IETF's [Request For Comments](https://en.wikipedia.org/wiki/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.
27+
28+
For Lit, RFCs are markdown files in the lit/rfcs repository.
29+
30+
RFCs have a structure as defined in the [RFC template](./0000-rfc-template.md), including these metadata and sections:
31+
32+
* Champion(s): The people making and maintaining the proposal. This can change over time.
33+
* Stage: Active, Implemented, Deprecated
34+
* Summary
35+
* Objective (goals and non-goals)
36+
* Motivation (background)
37+
* Detailed Design, including these recommended sections:
38+
* Implementation Plan
39+
* Backward Compatibility
40+
* Testing Plan
41+
* Performance and Code Size Impact
42+
* Interoperability
43+
* Security Impact
44+
* Documentation Plan
45+
* Downsides
46+
* Alternatives
47+
48+
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.
49+
50+
## When to use RFCs
51+
52+
RFCs must be created for new and "substantial" changes. "Substantial" is somewhat subjective, but some clear signs are:
53+
54+
* New packages
55+
* New modules, classes, directives, etc. in an existing package
56+
* Most new public-facing API
57+
* Breaking changes
58+
59+
Changes that do _not_ require an RFC:
60+
61+
* Internal implementation changes
62+
* Bug fixes
63+
* Most dev mode changes: warnings, etc.
64+
65+
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.
66+
67+
#### Relationship to Lit Labs
68+
69+
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.
70+
71+
## RFC Process
72+
73+
### Stages
74+
75+
RFCs go through the following stages during their lifetime:
76+
77+
* **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`.
78+
* **Rejected** When an RFC is rejected and its PR closed.
79+
* **Active** When an RFC has been accepted, and its PR merged, but hasn't yet been implemented.
80+
* **Implemented** When an RFC has been implemented and its feature released.
81+
* **Withdrawn** When a *previously accepted* RFC has been rejected or withdrawn due to new information, such as implementation difficulty.
82+
* **Deprecated** When a *previously accepted*, and possibly implemented RFC has been superceded by a new RFC.
83+
84+
### Before opening an RFC
85+
86+
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.
87+
88+
You may get this indication in several ways, from informal to formal:
89+
90+
* A feature request issue is closed with a request to open an RFC
91+
* A core team member directly invites you to open an RFC from a community or support channel like GitHub Discussions, Slack, or Twitter
92+
* You open a "[RRFC](https://github.com/lit/rfcs/issues/new)" (Requesting Request For Comment) issue in lit/rfcs and get positive feedback
93+
94+
### Opening an RFC
95+
96+
1. Fork the lit/rfcs repo
97+
2. Draft the RFC
98+
1. Add the RFC file to /rfcs in a markdown file named `NNNN-_descriptive-name_.md`
99+
1. Note the `NNNN` is literal. RFCs will not have an assigned RFC number when first opened.
100+
3. Open an RFC pull request
101+
1. Optionally share the draft on [GH discussions](https://github.com/lit/lit/discussions) or [Slack](https://lit.dev/slack-invite/) before opening a pull request
102+
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.
103+
104+
### Discussion and Iteration
105+
106+
RFCs must be discussed and reviewed by the relevant maintainers, Lit project leadership, and other stakeholders before being accepted or rejected.
107+
108+
#### Reviewers
109+
110+
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](../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.
111+
112+
#### Timeline
113+
114+
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.
115+
116+
#### Acceptance
117+
118+
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.
119+
120+
#### RFC Meetings
121+
122+
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.
123+
124+
### Updates and Amendments
125+
126+
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.
127+
128+
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.
129+
130+
Small changes to RFCs can be made to:
131+
132+
* Add clarifications
133+
* Update metadata and other non-design text (examples, documentation)
134+
* Changes to implementation, possibly based on implementor feedback
135+
136+
_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.
137+
138+
### Implementation
139+
140+
As RFCs are implemented, they should be updated to indicate so. The status is updated to *Implemented* and relevant PRs linked.
141+
142+
## Other RFC Processes
143+
144+
The projects have served as inspiration for our process:
145+
146+
* [Ember](https://github.com/emberjs/rfcs)
147+
* [npm](https://github.com/npm/rfcs)
148+
* [Fuchsia](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/docs/contribute/governance/rfcs/rfc_process.md)
149+
* [Vue](https://github.com/vuejs/rfcs)

0 commit comments

Comments
 (0)