RFC Process
Provide an RFC process that gives us a single source of truth, a history of decisions, and a Propose -> Review -> Accept lifecycle.
Problem Description
Our current way of discussing changes is spread across Google docs, Slack conversations, PRs, and face-to-face meetings. We don't have a single source of truth for decisions and technical documentation that is tied in with the products we deliver. It is also difficult to find the history of decsions and work out what has been accepted.
We need a system that gives us easy access to all decisions and discussions, as well as their history and the current state of everything.
Background
Confluence gives us spaces that we can edit, but there is no RFC and acceptance lifecycle to changes there.
Google docs allow us to get comments and feedback, but there is no real structure and no mark that a document is complete and accepted. They are also hard to find and search.
OpenStack is an open source cloud computing solution, and their developer base is a huge, totally distributed ecosystem.. Their RFC process is simple: text files in a git repository. There are PRs opened against the repo, and a website is generated from the files on merge.
Solution
We set up a new repo, ebury-blueprints. In this repo, we have code that builds simple text files into a static website, which can be deployed to an internal server.
PRs are opened against the ebury-blueprints repo when there is a new RFC.
The discussion happens on the PR, and when the RFC is accepted, it is merged. For more details on this part of the process please see the RFC lifecycle
The RFCs use rfc-template.md as a base.
This document is an example of using the RFC template.
RFCs should be updated when they have been implemented to show the actual implementation.
Folders and Indices
The markdown file should be placed in the appropriate folder (architecture, components, practices, processes, etc) and included in all relevant indices.
A document may appear in several indices, for example in the Components Index, the Domains Index, a project specific index like Ebury Mass Payments or a technology oriented index like Platform
Using blueprints
Running the blueprints development server:
$ make dev
The development site will run on http://127.0.0.1:8000/ and rebuild documents automatically as you edit them.
Building the production site:
$ make build
This will generate the static HTML version of the site in site/
Caveats
The process is very technically focused, if it was to be used for more than technical documentation and RFCs, we would need to look at other tooling.
Operation
This requires a new site, blueprints.ebury.rocks to be set up and monitored. A jenkins job will need access to deploy static HTML to it.
Security Impact
The blueprints site must only accessible to Ebury employees. Being behind the VPN should be enough here.
Performance Impact
N/A
Developer Impact
N/A
Deployment
N/A
Dependencies
The Jenkins job and hosting for the new site need to be set up by DevOps.