75 lines
3.6 KiB
Markdown
75 lines
3.6 KiB
Markdown
---
|
|
title: "Standard 1: RFC Format and Semantics"
|
|
number: 0
|
|
author: Robert Miles <khuxkm@tilde.team>
|
|
status: Approved
|
|
---
|
|
## Abstract {#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 {#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.](#doc-types))
|
|
|
|
- `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 {#semantics-of-system}
|
|
|
|
The RFC system for tilde boxes will be hosted at https://rfc.tildeverse.org/ and on the tildeverse gitea as [tildeverse/rfcs](//git.tildeverse.org/tildeverse/rfcs).
|
|
|
|
### Types of Documents {#doc-types}
|
|
|
|
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 {#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 {#submission}
|
|
|
|
An RFC should be submitted as a PR to the [git repo](https://git.tildeverse.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 {#procedures}
|
|
|
|
### Security Considerations {#security}
|
|
|
|
There are no security considerations to this document.
|
|
|
|
### Configuration Considerations {#config}
|
|
|
|
A subdomain of tildeverse.org has been provisioned for the RFC project, and a repo has been created, in accordance with this document.
|