100 lines
3.6 KiB
Markdown
100 lines
3.6 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 implicitly as [#procedural-section](#procedural-section)).
|
|
|
|
There are 2 sub-sections to the procedural info section:
|
|
|
|
- Security Considerations (tagged implicitly as
|
|
[#security-considerations](#security-considerations)) - If there are any
|
|
security reasons/concerns for the document, they MUST be subsections of this.
|
|
|
|
- Configuration Considerations (tagged implicitly as
|
|
[#configuration-considerations](#configuration-considerations)) - 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.
|