75 lines
3.5 KiB
Markdown
75 lines
3.5 KiB
Markdown
|
---
|
||
|
title: "Standard 1: RFC Format and Semantics"
|
||
|
number: 0
|
||
|
author: Robert Miles <khuxkm@tilde.team>
|
||
|
status: Accepted
|
||
|
---
|
||
|
## Abstract
|
||
|
|
||
|
This RFC defines the format used by an RFC. RFCs in this system are stored as Markdown files with YAML front-matter. RFC files MAY be stored with any extension commonly used by markdown files.
|
||
|
|
||
|
This RFC also defines the semantics of how the RFC system will work.
|
||
|
|
||
|
## Front-matter format
|
||
|
|
||
|
The front-matter MUST contain the following key-value pairs:
|
||
|
|
||
|
- `title`: The title of the document. Standards documents should be titled in the format `Standards X: Y` where X is the standards number and Y is the title of the standard. ([See below for an explanation of standards.](#types-of-documents))
|
||
|
|
||
|
- `number`: The canonical number of the RFC. Starts at 0 (this document) and counts up in decimal.
|
||
|
|
||
|
- `author`: The author of the document. May contain email.
|
||
|
|
||
|
- `status`: The status of this document. Should be `Accepted` or `Proposed`. (Rejected documents are not made a part of the repository.)
|
||
|
|
||
|
The front-matter MAY contain the following key-value pairs:
|
||
|
|
||
|
- `updates`: A comma-seperated list of RFCs this RFC updates.
|
||
|
|
||
|
- `updated-by`: A comma-seperated list of RFCs that update this RFC.
|
||
|
|
||
|
Note that the two lists should be added to in sequence; if RFC 2 updates RFC 1, then RFC 2 needs to have 1 in its `updates` and RFC 1 needs 2 in its `updated-by`.
|
||
|
|
||
|
## Semantics of the RFC System
|
||
|
|
||
|
The RFC system for tilde boxes will be hosted at https://rfc.tildeverse.org/ and on the tildeverse gitea as [tildeverse/rfcs](https://tildegit.org/tildeverse/rfcs).
|
||
|
|
||
|
### Types of Documents
|
||
|
|
||
|
RFC documents are simply requests. They are for simple things like defining how something should work or how something should be done.
|
||
|
|
||
|
Standards documents are like mandates. They require something. For example, this document requires a would-be submitter to follow this
|
||
|
format for RFCs. A Standards document can be amended by RFC documents, and any RFC documents in violation of a Standards document,
|
||
|
unless otherwise stated within the Standards document, are invalid.
|
||
|
|
||
|
### Procedural Section
|
||
|
|
||
|
Every RFC and Standards document should end with a procedural information section (id tagged as [#procedures](#procedures)).
|
||
|
|
||
|
There are 2 sub-sections to the procedural info section:
|
||
|
|
||
|
- Security Considerations (tagged [#security](#security)) - If there are any security reasons/concerns for the document, they MUST be subsections of this.
|
||
|
|
||
|
- Configuration Considerations (tagged [#config](#config)) - For example, if configs need to be changed due to the RFC.
|
||
|
|
||
|
### Submission guidelines
|
||
|
|
||
|
An RFC should be submitted as a PR to the [git repo](https://tildegit.org/tildeverse/rfcs). RFCs MUST come with a draft name.
|
||
|
|
||
|
For example, a draft name for an RFC to make tilde.chat allow IRC connections without SSL could be `draft-tilde-chat-without-ssl`.
|
||
|
|
||
|
The only time an RFC can omit the number tag in its front-matter is when it is a draft. Drafts do not have numbers and are of the
|
||
|
status `Proposed`. If or when an RFC is accepted, it will be given a number (at which time it MUST be renamed `rfcX.md`, where X is
|
||
|
the number). The status MUST be changed to `Accepted` and the number tag MUST contain the assigned number. When the former draft
|
||
|
meets these requirements, the PR will be merged.
|
||
|
|
||
|
## Procedural Information
|
||
|
|
||
|
### Security Considerations
|
||
|
|
||
|
There are no security considerations to this document.
|
||
|
|
||
|
### Configuration Considerations
|
||
|
|
||
|
A subdomain of tildeverse.org has been provisioned for the RFC project, and a repo has been created, in accordance with this document.
|