This document explains how to write an RFC.

What is an RFC?

RFC is an acronym for 'Request for Comments'. It is a social device use to float and polish an idea prior to implementation. It provides a basic description of a problem, proposed implementation with high (and sometimes low) level detail, an a roadmap for seeing the implementation move from idea to reality.

RFC's should be typically be reserved for 'big ticket' items where the implementation path is perhaps not clear from the outset and the problem needs to be systematically deconstructed in order to arrive at a viable solution.

An RFC should not be used for bug reports or trivial discussions - the overhead of compiling an RFC does not justify it.

An RFC should not consist only of a problem statement (use a standard issue for that).

How to write an RFC

RFC's should be written on the issue tracker and should consist of the following key elements:

• Title: The title should be prefixed with 'RFC' and should be succinct and explanatory. e.g. RFC: Implementation of a new Impact Function plugin loader. Using the 'RFC' acronym in the title will allow us to easily search for past and present RFC's.

• Problem statement: The problem statement should be annotated with the markdown heading #Problem which should should be followed by one paragraph that describes the problem that the RFC intends to address. The problem statement should be written in clinical, non-emotive language. For example this would be a bad problem statement: The new Impact Function loader is broken and sucks and makes me look bad at training courses. While these statements may be true, for an RFC we need rather a factual assessment e.g. The new impact function loader regularly fails (see Issues #1, #2, #5). We need to implement a new plugin loading mechanism which is robust and will work well on all platforms.

• Duration: The duration section should be annotated with the markdown heading # Duration. Each RFC should express a duration during which the commenting period can take place. At the end of this deadline the decision may be made to extend the deadline if time is needed for further investigation or discussion. When an RFC is extended the extension should be appended and annotated as per the example below:

  # Duration
  
  1 August 2014 (extended by @timlinux by agreement on the inasafe-dev mailing list)
  30 July 2014
  

• Current state: This section should be annotated by the # Current state heading. It should be contain if the RFC is in draft, awaiting feedback, closed etc.

• Proposer(s): This section should be annotated by the # Proposer heading. It should be followed by a bullet list of one or more persons who have developed the RFC. e.g.

  # Proposers
  
  * Tim Sutton
  * Charlotte Morgan
  

• Detail: This is a free-form section that should be annotated with the # Detail heading. The detail section should extend the initial problem statement with additional details that describe the situations in which the problems arise, which the current situation is in fact a problem and so on.

• Proposal: This should be annotated with the # Proposal markdown section header. It should contain a detailed breakdown of how the problem should be resolved including detailed code listings, diagrams and other supporting materials needed to present the case and implementation roadmap for the proposed changes. See for example #577. The effective use of diagrams, screenshots and sample code listings cannot be over emphasised - the reader should be able to fully understand the proposal and its implications of the current software architecture. This section should be broken up using ## subsections as needed.

• Record of Votes: This section should be annotated with a # Record of votes markdown section header. In this section the RFC convenor should record all the final votes for the RFC in the following manner:

  Vote	Name
  +1	Tim Sutton

• Resolution: This section should be annotated with a # Resolution markdown section header. Here you should indicate whether the RFC is in draft, submitted for approval, approved, denied or shelved to be retabled at a future date.

• CC: This section should be annotated with # CC markdown section header.

Commenting on an RFC

Use the commenting tools in github issue tracker to add comments to the RFC. The original RFC should be updated as discussion evolves in order to always reflect the current state of the proposal.

Approval of an RFC

A simple voting system should be used whereby interested and affected parties add a comment to the RFC according to the following scheme:

• -1 - I strongly disagree with the proposal
• 0 - I am not engaged enough with the proposal to be able to provide an inform assent or dissent. This is tacit agreement to continue if there are sufficient +1 votes or to abstain if there are sufficient votes.
• +1 - I strongly agree with the proposal

If sufficient requests are made (or insufficient feedback is provided) the proposer should call the upon the interested and affected parties to cast their votes, or extend the deadline.

When casting a vote of disagreement, the voter should indicate whether they will be willing to entertain a revised version of the proposal, or if they reject the idea outright.

Implementation of an RFC

Once the RFC comment period has concluded and approval has been given, the implementation should be carried out as a series of github issues which back reference the original RFC issue. The individual issues will break down the RFC into atomic actionable components and optionally distribute the actual implementation work between one or more developers. Backreferences to the RFC will automatically show up on the original RFC in the comment trail maintained by GitHub.

Template

The following template is provided for your convenience to use when creating new RFC's:

# Problem


# Duration


# Proposers


# Detail


# Proposed solution



# Record of votes

+1 Tim Sutton

# Resolution

# CC

@Charlotte-Morgan 
@vdeparday 
@ingenieroariel 
@ismailsunni 
@akbargumbira 
@mbernasocchi