0001-rfc-process

[savente93]

• Feature Name: rfc-process
• Start Date: 2023-07-18

Summary

RFC is a workflow for making and recording decisions, which helps to not just document which changes are made but the rationale behind them, as well as give the community opportunity to comment and give feedback on big proposals.

Motivation

For long living projects which is worked on by many different people throughout it's lifecycle, it can be difficult to understand why certain decisions were made and thus not retread old ground, as well as gaining clarity about the intent behind a change. It is also desirable to be easily communicate changes and rationales to stake holders. The RFC process is meant to address these needs.

The RFC is meant to mainly facilitate two processes: making decisions and recording decisions. It provides a framework for aspects involved in big fundamental decisions that both should be taken into account and, ideally recorded for future reference by new contributors or stakeholders.

Finally, as an open source project that is mainly meant to facilitate common workflows for it's users, it is highly desirable to maintain an open communication channel with it's users. RFCs both serve to help users stay informed on the status of tje project as well as give them influence the direction of HydroMT in a way that is useful to them. This way we can make sure that HydroMT actually facilitates the use cases that users have.

The aim of this RFC is to, perhaps ironically, codify the RFC process as an official policy for decision making within the HydroMT core team. This means that large decisions with wide spread impact should go through the RFC process whether they are deemed controversial or not. How the process facilitates these different kinds of proposals will be discussed in the next section.

Guide-level explanation

• The RFC process is started by the author of the RFC copying the template called 0000-rc-template and filling it out, just like this RFC itself.
• Making an RFC is a lot of work and a slow process, and that is somewhat by design. The intention of this process to be accessible to anyone, but have a somewhat high bar for entry to keep unnecessary communication to a minimum. Decisions big enough to warrant an RFC should also be taken with care, thus thoughtful deliberation is key!
• Note that anyone is allowed and even encouraged to open an RFC for any sufficiently large idea. Though note that is is not the appropriate channel for general feature requests. In appropriate or incomplete RFCs may be closed and asked to submit again when they meet the bar for entry. This does not mean however than an RFC needs to be perfect to be opened. It is meant to facilitate discussion, so it is okay for there to be unresolved questions when an RFC is opened (there is even a dedicated section for it!)
• Users who have trouble writing an RFC are encouraged to reach out to the core team for help. They can provide guidance on how to prep an RFC for submission.
• When an RFC is Opened, it is opened for discussion. Anyone should be able to comment on it to help work out any unresolved questions or submit points of consideration.
• After being open for a certain period and all remaining uncertainties have been worked out the team will issue a Final Call for Comment (FCC) s through whatever appropriate channels exist. In this FCC should be mentioned how long the call will stand for, typically between 1 and 4 weeks. This will be the final opportunity for anyone to submit comments and points of view.
• After The FCC has expired, the RFC will be locked and comments will no longer be accepted. At this point the RFC will be either Accepted or Rejected. Closed RFCs will be codified within the repository in an Architectural Design Record (ADR), And ADR is essentially the final version of an RFC.
• Note that ADRs are essentially akin to decisions by a court of law. They should be upheld whenever possible but can be overturned, superseded or extended by other ADRs as result of other RFCs, but not very easily (again, this is largely by design as this provides stability to both users and developers).
• As such, while the ADRs are integrated by way or PR, they are not in any way meant to be controversial or open to discussion. If everything goes as it should, once an ADR pull request is opened all the relevant discussions should already have been had. Therefore the merging of an ADR is not subject to as many checks as for example closing an FCC.
• For uncontroversial or historical decisions the team may decide to skip the RFC process and move straight into writing and ADR, though this should be done with extreme discretion.
• The aim of an ADR is to provide all the necessary context for people wishing to be involved with a decision or return to a certain decision in the future, as well as serve for a reference for anyone trying to implement features associated with the RFC.
• This RFC itself will serve as an example of the process.
• As a final note to prospective RFC authors: RFCs are like PR requests in that smaller RFCs have more chance of getting accepted without much opposition, so you are encouraged to break large topics up into smaller RFCs if this is possible.
• ADRs shall contain references to other relevant ADRs. For example, if an ADR is superseded by another, a link to the superseding ADR should be added at the top of the document. RFCs may contain these references but as RFCs are meant to be more self contained, this is not required.
• Closed RFCs shall bare a link to the corresponding ADR PR in the repository. This can be done either by the author or the responsible core team member.

Reference-level explanation

• Both initial RFCs and final ADRs should follow this template
• The discussions on the RFCs should happen in the github discussion section, while ADRs should be added to the repository by way of PR.
• When an FCC is closed the corresponding RFC should be locked and comments should not longer be allowed.

Drawbacks

• An RFC framework could be deemed to cumbersome for a small team. As mentioned before an RFC can be a lot of work, though this is partially by design.
• the RFC might feel like to much administration to some people
• It might be a hindrance for people who struggle with proposal writing

Rationale and alternatives

• Why is this design the best in the space of possible designs?
• What other designs have been considered and what is the rationale for not choosing them?
• What is the impact of not doing this?
• Why should we do this? Is there perhaps another tool or framework that could achieve this better, that we could potentially contribute to?

Prior art

The RFC process has been adopted by many prominent open source projects or other prominent organisations, including but not limited to:

• Rust
• ReactJs
• VueJs
• npm
• NixOs
• SvelteJs
• AWS-CDK
• AWS
• GitLab
• Internet Engineering Task Force
• SquareSpace
• Spotify
• Python
  (note that the above list only contains instances for which public sources/citations were available)

While there has been some public criticism of the RFC process, e.g.

• https://www.ncameron.org/blog/the-problem-with-rfcs/
• https://www.reddit.com/r/rust/comments/xif5q0/the_rust_rfc_process_does_not_seem_as_amazing_as/
  this has been not about the RFC process fundamentally but rather the implementation of it. It should also be noted that the criticism tends to arise in situations where RFCs are both very complex and fairly frequent, neither would apply to HydroMT at this point in time.

Other than that the RFC process is generally well regarded in the software engineering industry as is evidenced by the list of projects and organisations following this workflow (see above).

To emphasise the point there is also a decent amount of literature regarding RFCs, including:

• https://www.rfc-editor.org/rfc/rfc1000 (IETF)
• https://journals.sagepub.com/doi/abs/10.1177/1043659609334678 (Journal of Transcurlural Nursing)

While not technically about RFCs there are also numerous scientific publications ragarding the policies of writi8ng ADRs. ADRs and RFCs are incredibly closely linked to the point that for the purposes of this discussion the author considers them interchangable. Citations include:

• https://ieeexplore.ieee.org/abstract/document/9801811
• https://ieeexplore.ieee.org/document/9928205
• https://ieeexplore.ieee.org/document/9425823
• https://ieeexplore.ieee.org/document/7365797

Unresolved questions

• What channels would be appropriate for advertising RFCs, FCCs and ADRs both within and outside of Deltares
• How long should an FCC typically stand for? Here the balance is between giving users an appropriate amount of time to respond and not unnecessarily halting development.

Future possibilities

N/A

[savente93]

This format was briefly discussed during our standup. The conclusions were:

• This is a useful way of framing and recording decisions, but should be done in a way that should not become a burden.
• As long as contributions and involvement comes mainly from the HydroMT Core team, a formal FCC is not necessary. Once outside interests start presenting themselves we can reevaluate whether this is something that would be useful on a case by case basis
• We will try out this workflow for a while and then reevaluate down the line how it suits our needs.