User Tools

Site Tools


rfc

Table of Contents

RFCs

Rust has a great RFC process. https://github.com/rust-lang/rfcs. Let's borrow their format (or whatever parts apply) to describe any large requests for changes.

Process

RFCs are how we make proposals for changes as a community. They let everyone participate in the OpenAg design process. The process:

  • Have an idea for a change or feature
  • File an issue
  • Use the template below
  • The community is invited to provide feedback on the GH issue.
    • Make sure to provide feedback on the GH issue so that your feedback isn't missed.
    • We leave a wide-enough window of time (2 days minimum) so that people can provide feedback across time zones.
  • The core team will review RFCs, taking into account feedback from the community and make a decision about how to move forward.

Template

The basic template of the RFC looks like this:

  • Summary: One para explanation of the feature.
  • Motivation: Why are we doing this? What use cases does it support? What is the expected outcome?
  • Details: This is the bulk of the RFC. Explain the design in enough detail for somebody familiar with the project to understand and implement. This should get into specifics and corner-cases, and include examples of how the feature is used.
  • Drawbacks: Why should we *not* do this?
  • Alternatives: What other designs have been considered? What is the impact of not doing this?
  • Unresolved questions: What parts of the design are still TBD?

Copy/paste-able markdown template:

## Summary

## Motivation

## Details

## Drawbacks

## Alternatives

## Deadline for comments
* Deadline for comments on this RFC is <day> YYYY-MM-DD.

Why this template is great:

  • Maps out the problem space.
  • Builds a culture of seeing problems from multiple points of view, considering multiple solutions.
  • Acknowledges tradeoffs and makes them explicit (engineering is all about tradeoffs)
  • Makes unknowns explicit
rfc.txt · Last modified: 2017/06/08 17:43 by rbaynes