RFC = Request For Change.

An RFC is a formal request for something to change. Even though change is arguably a fractal concept (specifying an inexistent subsystem afresh can be construed as change too), this issue is strictly concerned with the process of:

proposing an alteration of an existing spec document, recording the change in a traceable, structured, archivable manner so it can be understood decades later.

For a case study, imagine we want to modify the peer ID spec to alter the string representation, as is precisely the case of libp2p/go-libp2p-core#41.

The Request For Change needs to be documented in a form that captures, at least:

• Context/status quo.
• Rationale/motivation for change.
• Proposed change.
• Backwards-compatibility analysis.
• Best-effort evaluation of impact on existing implementations.
• Proposed rollout strategy.
• Alternatives considered.

Options

Other approaches exist, but these are the ones that I want to weigh now:

1. Submit a PR that modifies the specification document(s), explaining the above points in the PR's description.

   This has the upside of simplicity, but has many downsides, namely:

   • the source of truth and archive is spread across a proprietary technology (GitHub PRs) and the repository.
   • changes in PR descriptions aren’t versioned (they are traceable via GitHub's UI, but there are no guarantees of history preservation, and one can't associate a commit message to a change in a PR description).

2. Create an RFC template and a top-level RFC folder in this repo to archive documents of this kind, including a numbering system and a naming scheme.

   Each RFC PR carries (at least) two artifacts:

   1. An instantiation of the RFC template explaining the change.
   2. The changes on the specification(s) themselves that are affected.

   This way, the commit history of this repo will store, archive and index of history of a spec, as it changed over time.

   A spec document itself can thus be regarded as a consolidated text (like in EU legislation) that integrates the initial text + all successive amendments by way of RFCs.

I lean towards solution 2.