Streamline the RFC writing process

Summary

Streamline the writing and publishing of RFCs by relying on markdown and dedicated spellcheckers and linters.

Motivation

ReStructuredText (RST) is currently used for writing and publishing Arch Linux RFCs. While used in specific ecosystems (e.g. Python) and in publishing, it is considered less widespread and more exotic than markdown.

Markdown is widely adopted across many platforms and tools, including GitLab and hugo (which is used for generating the static website at https://rfc.archlinux.page/). Additionally, a large set of linters and check tools exist for it and due to its widespread use, many people have a basic understanding of how to use it.

Many RFC drafts start out in pads using our HedgeDoc instance, which allows collaborative writing of markdown documents. Converting these drafts to RST before introducing them on the issue tracker is tedious and error-prone, especially for long RFCs.

GitLab's integration for rendering RST is subpar and as such many directives are not rendered correctly when accessing the page of an RFC document in a merge request. Contributors and reviewers have to rely on building the resulting website for a clear review path, which is time consuming.

A large part of the Arch Linux team does not consist of English native speakers. Frequently we see the need for various spelling and grammar fixes in the RFC review process. This may be discouraging to the people writing the RFC and should be streamlined with automation.

Overall, preparing an RFC may be quite intimidating and tedious, both on the grounds of missing automation for correcting spelling issues and due to not being familiar with RST.

Specification

In an initial step, we will convert the current RST-based RFC template to markdown and adapt integration accordingly.

In a second iteration we will add a configurable spellchecker (typos), a code linter (markdownlint) and a prose linter (vale), which will be integrated with the central build system and CI of the project. The markdown line length check is disabled to facilitate having a single sentence per line, making diffs easier to review and avoiding text rewrapping when changes occur in a hunk.

The following configuration items should be disabled for markdownlint:

• MD002 (first header should be a top header, for hugo top tags)
• MD013 (line length)
• MD024 (multiple headers with the same content)
• MD041 (first line in file should be a top level header, for hugo top tags)

Implementers will evaluate improvements of the configuration on the fly.

The vale configuration will be generated initially and expanded upon iteratively.

In a final step we will convert all existing RFCs from RST to markdown, which has the added benefit of not using two differing systems in the longterm.

Drawbacks

Spellcheckers and prose linters may raise "false positives" without proper configuration. Respective configuration files have to be maintained and potentially extended with each new RFC by e.g. adding new technical terms. Prose linters may require more in-depth configuration (initially or short to midterm) to arrive at a good result, which implies an iterative configuration process. Additional linter rules may be added upstream and will need evaluation when using them in the RFC project.

Unresolved Questions

None.

Alternatives Considered

Only adding an additional markdown version of the RFC template would offer people to choose markdown or RST when writing RFCs. However, this leads to higher maintenance costs long-term if two systems are used and have to be maintained. Additionally, further using RST comes with the downside of poor rendering on GitLab and worse linting integration.