RFC presentation

Based on the research found over at RFC driven development#.

Key points

  • Code reviews improve code quality, RFC improve design quality.

  • Document design process, instead of writing inside WO notes/ticket descriptions

  • Less overhead when it comes to code reviews

  • More overhead when it comes to designing. Forces us to think before we code.

  • Not to be used every time. It’s a tool for bigger tasks.

  • FOSS friendly. Not just for Iver employees that may author and review designs.

  • Drawbacks

    • Takes time
    • Endless discussion
    • Incompatible with SCRUM
    • Unclear what needs RFC
    • RFC and actual implementation may differ
    • Some RFC reviews are faster than other, leading to bottlenecks
    • RFC implementation status (is it in progress/completed/pending?)
    • Fear of discussions you don’t grasp
    • Licensing RFCs

  • What is needed to start writing RFCs?

    • RFC template
    • Somewhere to store them
    • Someway to read them
    • Someway to review them

  • Specs for hosting your own

    • Autogenerated list of all RFCs
    • Autogenerated search
    • Linking to each RFCs implementation issue/ticket
    • Showing status of each RFCs implementation

  • RFC template

    • We want simple yet effective. As with issue templates, the size of it should correlate with the size of the project. Wharf is not a big project, while for example Rust is.

      See examples from Concrete RFC usage#.

Manuscript

  • What are RFCs

    • For internet standards:

      • Documentation of standards
      • Spec sheets

    • Documented design decisions

    • Invitation to discuss design (literatly “Request for comments”)

  • What does their RFCs look like?

  • IETF or open source, they still share some things:

    • Written in ink. Once written, they are not changed. Outdated maybe, but never altered.

    • Reviewed before considered “published”.

    • Nothing without an implementation.

  • RFC mythbusting

    • Only for IETF (nope anyone can do it)
    • Only for writing standards or language specs (nope they’re design documents)
    • RFCs are specs (nah just suggestions)
    • RFCs are super complicated and tedious (nah they’re just writing down the design chats we already sometimes have)
    • RFCs will lead to a lot of reading and writing of natural language (actually yes, but get used to it!)
    • Scares pot. contrib. away (can if done poorly, just like with GitHub Issues)

  • Benefits of Code reviews

    • Make code cleaner:

      • Code authors tries to evade future nitpicks
      • Naming strategies/conventions are shared and complied with
      • Code design patterns gets preferred

    • Knowledge transfer

  • Cons of not using RFCs

    • design discussions during code reviews
    • not that many “high level” discussions

  • Existing RFC adoptations (See RFCs in the wild#)

    • IETF’s usage of RFCs
    • Other’s usage of RFCs: Rust, Swift, .NET, React.js, …

  • RFC structure (See Concrete RFC usage#)

    • Metadata
    • Summary/introduction/description
    • Motivation/why we need this
    • Explanation as docs, as if it was already implemented
    • Implementation suggestion, detailed
    • Compatibility
    • Drawbacks
    • Alternatives
    • Unresolved questions
    • Future possibilities
    • Acknowledgments/don’t sue us plz

  • RFC lifecycle

    • write it (who? where? when?)
    • review it (how many reviewers?)
    • finalize or postpone it (who sets the deadline?)

  • Demo: Look at creating a RFC for Rust

  • What is needed to start writing RFCS?

    • Base requirements
    • Other’s bars (quote from Rust’s “lightweight” note)
    • Our bar

  • Suggested procedure: GitHub Pages + Jekyll (just-the-docs)

  • Issues with RFCs (See Issues with RFCs#)

    • Takes time
    • Endless discussions
    • Incompatible with Scrum
    • Unclear what needs RFC
    • RFC and actual implementation may differ
    • Some RFC reviews are faster than others
    • Fear of discussions you don’t grasp
    • Licensing RFCs

  • Benefits of RFCs (See RFC driven development#)

    • Enforce thinking before coding
    • Open discussion, ANYONE can participate
    • Potentially more perspectives (from QAs, testers, DBAs, architects)
    • Increased feeling of responsability
    • Fewer “Why wasen’t I consulted about X?” questions
    • Only participate at the right level of abstraction that suits you

  • Closing words

logo