Proposed updated to RFC process: make it clearer when later RFCs supersede earlier RFCs

[Kayce Basques]

Hi Eng Council, we need a mechanism for better communicating when a part of an RFC has been superseded by a later RFC. And new RFCs should have an explicit section detailing what parts of previous RFCs are being superseded.

For example, RFC-0111 says that hardware cryptographic acceleration support is optional ("recommended") whereas RFC-0151 makes it mandatory.

(Footnote: it's not obvious at all that RFC-0151 is superseding RFC-0111. If I understand correctly, the -march=armv8-a+simd+crc+crypto argument in the code block is where the superseding is happening. This is exactly why there should be an explicit section prompting authors to detail how previous RFCs are being superseded.)

There is precedence for this in the Rust RFC process, from The RFC life-cycle:

More substantial changes should be new RFCs, with a note added to the original RFC.

I will stop here and check if you all agree with this proposal before discussing implementation.

[James Robinson]

Hi Kayce,

The RFC amendment process discusses this situation: https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/rfc_process#process_to_amend_rfcs. In particular it says that we should amend existing RFCs when new accepting new RFCs change what was previously agreed. Do you think that process covers these use cases? Do you have a suggestion for how we could use or improve this mechanism to handle these cases?

- James

--
All posts must follow the Fuchsia Code of Conduct https://fuchsia.dev/fuchsia-src/CODE_OF_CONDUCT or may be removed.
---
You received this message because you are subscribed to the Google Groups "eng-council-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to eng-council-dis...@fuchsia.dev.
To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/eng-council-discuss/CAGBRUqWdJgrd_Fc1J7U5S5y9BsR0nVhMB1zQ8f6_cUDUYBsETg%40mail.gmail.com.

[Mitchell Kember]

Based on the link James gave, I think RFC-0111 should have a footnote/aside linking to RFC-0151 explaining the optional → mandatory change.

I'd also note that fully tracking the accuracy of and relationship between RFCs can get pretty complicated. I try to do this for FIDL RFCs in fuchsia.dev/fuchsia-src/contribute/contributing-to-fidl/design-history#current_status, so that newcomers can get a sense of the history and understand what is and isn't outdated. There are a lot of categories and edge cases.

To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/eng-council-discuss/CAD73mdKpWTqT0%3D_wNw43UN_Y4ug-inOYTFzqqv0FFoc0GWiFOg%40mail.gmail.com.

[Kayce Basques]

Whoops! I did indeed see that section but on my first readthrough I thought it didn't cover the situation I'm discussing here. After reading it again just now, I see that it totally does:

If the design in the original RFC is being deprecated, amend the original RFC to call this out and reference the new RFC.

That is exactly the kind of guideline I was looking for.

There is still one thing outstanding: I think the RFC template should have an explicit section that prompts authors to outline how they are superseding any previous RFCs. One might argue that this is already covered in the "Design", "Backwards Compatibility", or "Documentation" sections, but I think it should be much clearer and more explicit.

I know this puts more work on authors but I think it will be a win-win for everyone. It will be easier for Fuchsia users/contributors to build an accurate mental model of our current design. And it will nudge RFC authors to rigorously think through their design in terms of previous RFCs. I know that authors and reviewers already implicitly do this but it's such a core part of the whole purpose of RFCs that I can't see why we wouldn't prompt for this more explicitly.

[James Robinson]

On Mon, Mar 13, 2023 at 3:18 PM Kayce Basques <ka...@google.com> wrote:

Whoops! I did indeed see that section but on my first readthrough I thought it didn't cover the situation I'm discussing here. After reading it again just now, I see that it totally does:

If the design in the original RFC is being deprecated, amend the original RFC to call this out and reference the new RFC.

That is exactly the kind of guideline I was looking for.

Great. I do think this language is too subtle - you are definitely not the first person to miss this and I'm sure you will not be the last. Can you think of a way to make this clearer? Perhaps the language qualifying the "design" portion comes across as too restrictive of the cases this process is intended to cover? 

There is still one thing outstanding: I think the RFC template should have an explicit section that prompts authors to outline how they are superseding any previous RFCs. One might argue that this is already covered in the "Design", "Backwards Compatibility", or "Documentation" sections, but I think it should be much clearer and more explicit.

I know this puts more work on authors but I think it will be a win-win for everyone. It will be easier for Fuchsia users/contributors to build an accurate mental model of our current design. And it will nudge RFC authors to rigorously think through their design in terms of previous RFCs. I know that authors and reviewers already implicitly do this but it's such a core part of the whole purpose of RFCs that I can't see why we wouldn't prompt for this more explicitly.

I agree that given observed history we should forefront this part of the process. The template is a good place to prompt authors to consider this. I wonder if we should also prompt reviewers to consider this aspect as often reviewers will have more context on relevant history than the author in their specific areas of expertise.

[Curtis Galloway]

If only we could get AI to help us review RFC conflicts :-)

Given the way this particular conflict was not so obvious, maybe a prompt in both the template and review guide would be helpful to call out cases like this where there is an implicit change.  We could even use this as a concrete example - if there are others from FIDL they might be helpful as well to include.

In cases where the intention to override a previous RFC was not clear, I assume everyone agrees that the solution is to just propose an additional RFC to record an explicit decision about the topic in question?  Would that be a good idea in this case to make it clearer that we already amended the requirement for crypto instructions?

--Curtis

[Alice Neels]

Should we add a template section about "RFCs modified"?

To view this discussion on the web visit https://groups.google.com/a/fuchsia.dev/d/msgid/eng-council-discuss/CA%2BmatrwJZXM_HLgxaQzXNvOHL2bR6_W%2BVzDugmcjZ83y5WF0Mw%40mail.gmail.com.

[Kayce Basques]

I will be out for most of this week but will keep the ball rolling next week by proposing some updates to the Process to amend RFCs section and template in a CL.

In cases where the intention to override a previous RFC was not clear, I assume everyone agrees that the solution is to just propose an additional RFC to record an explicit decision about the topic in question?  Would that be a good idea in this case to make it clearer that we already amended the requirement for crypto instructions?

The existing Process to amend RFCs section seems to support that approach:

In the new RFC, please reference the original RFC(s) and explicitly call out the type of change in the title, e.g., Addendum. 

[Roland McGrath]

This is a bit afield from the amendment process discussion, though I think it's highly valuable to improve and apply clarity in amendment cases.

But I don't think the case cited is pedantically speaking an amendment to RFC-0111 by RFC-0151.  That is, RFC-0111 is on the general subject of how arch-specific requirements should be developed, and it has as examples some details about ARM and x86.  RFC-0151 doesn't change that general rationale, and as examples what RFC-0111 says about ARM and x86 are still valid examples.  RFC-0151 actually formally defines the individual arch-specific requirements, IMHO for the first time actually formally, for ARM, as RFC-0073 did for x86.

That being said, amending the text of RFC-0111 both to make its examples consistent with current actual arch-specific details, and to be more clear that it is talking about the general case, seems helpful.

I'm not convinced we want to change RFC-0111's policy to say that cryptographic features are strictly required in any future arch-specific requirements defined for a future architecture, though perhaps we do and that can be debated.  But I definitely don't think we've already changed the policy RFC-0111 formalizes in that way.  It's just that RFC-0073 and RFC-0151 define arch-specific policies that are more stringent as instances than the RFC-0111 requires of the whole class.  So IMHO it does require a fresh review process (AFAICT another RFC) to agree to change the RFC-0111 policy.

Note that the recent RFC-0211 defined the initial arch-specific policy for RISC-V.  Though that is very likely to be amended later as the RISC-V support develops, it as ratified by RFC does not require any cryptographic ISA features.  So if RFC-0111 were amended today to indicate general policy change, RFC-0211 and RFC-0111 would be in conflict.  If RFC-0111 is simply updated to make its examples match current policies and/or to clarify that it is not the authority on arch-specific policies but only the policy guidelines for how arch-specific policies should be decided, then there remains no conflict.

On Mon, Mar 13, 2023 at 2:27 PM 'Kayce Basques' via eng-council-discuss <eng-counc...@fuchsia.dev> wrote:

[Kayce Basques]

Thanks for the details, Roland. Your rationale makes sense. RFC-0111 puts forward general policy and provides some arch-specific examples for clarity whereas RFC-0151 is defining arch-specific requirements. I will review RFC-0111 and RFC-0151 again to see if there are general updates for me to make along these lines.

One potentially complicating factor is that the author of RFC-0151 is no longer actively working on Fuchsia. We probably have processes set up to handle this, just figured it might be relevant to mention.

[Roland McGrath]

I don't think the original RFC author has a special place in determining future updates, even if they are still on the team. Updates to past RFCs are either trivial (typo fixes, link updates, etc.) or go through the same consensus review process as the original author went through with the RFC.

[Kayce Basques]

Here are the proposed general updates to the process doc and template: https://fuchsia-review.googlesource.com/c/fuchsia/+/822970

I will propose RFC-0111/RFC-0151 updates in a different change.