diff --git a/docs/rfcs/0000-template.md b/docs/rfcs/0000-template.md new file mode 100644 index 000000000000..b20df2eb8147 --- /dev/null +++ b/docs/rfcs/0000-template.md @@ -0,0 +1,49 @@ +--- +layout: page +title: +permalink: /docs/rfcs/ +--- + +* RFC PR: [](https://github.com/mozilla-mobile/android-components/pull/<#>) +* Start date: YYYY-MM-DD (day of posting) +* End date: YYYY-MM-DD (initial deadline for feedback, subject to blocking changes required) +* Stakeholders: , + +## Summary + +This section should include a brief description of the proposal. + +## Motivation + +This section should include reasoning about why the proposal is useful. Examples, specific scenarios, +open bugs, records of performance metrics, and other empirical data are beneficial to include here if available. + +## Guide-level explanation + +This section should include a high-level walkthrough of the steps required to implement the proposal. + +## Reference-level explanation + +This optional section should include a detailed walkthrough of technical steps or code changes that +will be required to implement the proposal. Code samples and prototypes are beneficial to include here. + +## Drawbacks + +This section should include any drawbacks to the proposal. This section can be considered optional, but is highly encouraged in order to facilitate healthy debate. + +## Rationale and alternatives + +This section should include any alternative proposals considered, as well as the rationale for why +they were not selected for the proposal. This section can be considered optional, but is highly encouraged in order to facilitate healthy debate. + +## Prior art + +Optional section with links to any similar proposals or other documentation that shares concepts with the proposal. Consider looking to sources outside Mozilla as well. + +## Unresolved questions + +Questions from the proposal author or from reviewers that are not yet resolved. + +## Artifacts + +Links to any additional documentation or other artifacts that were initially included with the RFC, for historical context. \ No newline at end of file diff --git a/docs/rfcs/0013-rfc-process-updates.md b/docs/rfcs/0013-rfc-process-updates.md new file mode 100644 index 000000000000..96380385e935 --- /dev/null +++ b/docs/rfcs/0013-rfc-process-updates.md @@ -0,0 +1,39 @@ +--- +layout: page +title: RFC process updates +permalink: /docs/rfcs/0013-rfc-process-updates +--- + +* RFC PR: /* TODO */ +* Start date: 2024-02-20 +* End date: 2024-03-22 +* Stakeholders: @jonalmeida, @boek + +## Summary + +Clarify requirements for RFCs by introducing a README and a template. + +## Motivation + +- The scale of the Firefox Android team has grown substantially since the RFC process was first introduced. +- More external teams are using and contributing to Android Components. +- Approval or rejection of a proposal has required periods of time that can slow implementation. +- Stakeholders have either been implicit by sharing RFCs in various communication channels, or an author must be expected to correctly select reviewers that lack explicitly documented ownership of affected areas. + +## Guide-level explanation + +This proposal suggests improving the RFC process by introducing the following: + +- an RFC template +- a guide for when RFCs are appropriate and when they are not needed in the form of a README +- explicit stakeholders for RFCs +- an initial deadline for each RFC +- a new RFC section, "artifacts" which contain links to any additional artifacts introduced alongside the RFC +- updating our CODEOWNERS file to better facilitate ownership for new Firefox Android "groups" and external teams + +Each of these updates are handled as part of this RFC, with the exception of updating the CODEOWNERS file. That will need to undergo a discovery process and communication between Firefox Android groups and other teams. + +## Artifacts + +[README](./README.md) +[0000 RFC Template](./0000-template.md) diff --git a/docs/rfcs/README.md b/docs/rfcs/README.md new file mode 100644 index 000000000000..76c0b3968304 --- /dev/null +++ b/docs/rfcs/README.md @@ -0,0 +1,45 @@ +# The RFC Process + +An RFC (**R**equest **F**or **C**omments) is a process through which contributors can solicit buy-in +for proposed changes to the codebase and repository at-large. It was introduced in the first RFC, +[0001-rfc-process](./0001-rfc-process.md), which includes additional details about the reasoning +for including the process. + +This is an overview of what kind of changes benefit from or require the consensus-building that the +RFC process provides, as well as a brief guide on how to draft them. + +## What kinds of changes require an RFC? + +1. Substantial changes to public APIs in Android Components, like the changes found in [0003 Concept Base Component](./0003-concept-base-component.md) and [0008 Tab Groups](docs/rfcs/0008-tab-groups.md). +2. Changes to process that affect other teams, like the changes found in [0001 RFC Process](./0001-rfc-process.md), [0013 Add stakeholders to RFCs](./0013-rfc-process-updates.md), and [0007 Synchronized Releases](./0007-synchronized-releases.md). +3. Proposals for changes to areas of the codebase that are owned by CODEOWNERS outside the author's team. + +## What kind of other changes can an RFC be useful for? + +1. Announcing a rough plan for changes to a public API you own in order to solicit feedback. +2. Soliciting feedback for architectural changes that affect the entire codebase, like [0009 Remove Interactors and Controllers](./0009-remove-interactors-and-controllers.md). + +## How to contribute an RFC + +There is a [template](./0000-template.md) that can be useful for structure. While drafting +a proposal, consider the scope of your changes. Generally, the higher the impact the changes will have +on downstream consumers of APIs, other teams, or users the more detail the RFC should include. Detail +would be things like example use cases, prototypes, and considered alternatives. + +### Artifacts + +Include additional documentation artifacts that may be useful in the context of the RFC as part of the +patch. + +### Stakeholders + +Stakeholders are required for each RFC. They will have the final say in acceptance and rejection. +Include at least 2 people as stakeholders: a CODEOWNER of the affected area and another (preferably a Firefox for Android team member). + +Stakeholders should be active in the RFC process - they should ask to be replaced if they do not have bandwidth to get the RFC finished in a short time span. This is to help the RFC process remain nimble and lightweight. + +### Deadlines + +An initial deadline should be included in each RFC. This should usually be at least a week, so plan accordingly. +For more substantial changes, it can be useful to push that to 2 or 3 weeks so that there is more opportunity for feedback from people that are not stakeholders. +Blocking feedback can push these deadlines back, but they should be updated appropriately so that interested parties have a clear understanding of timelines. \ No newline at end of file