search

libp2p / specs

Technical specifications for the libp2p networking stack
https://libp2p.io
1.52k stars 272 forks source link

Framework specification: formalising the RFC process #198

Open raulk opened 4 years ago

raulk commented 4 years ago

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 https://github.com/libp2p/go-libp2p-core/pull/41.

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

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.

yusefnapora commented 4 years ago

I agree that having the decision record is important, and in general will always pick the solution in which important data is in version control. So I'm also leaning towards option 2.

However, the exchange of commentary on a PR is often as valuable as the initial description, which is one of the benefits of the first option, since some of the context from the discussion may not make it into the RFC document. Arguably though, being forced to distill the commentary into the RFC itself should end up being a good thing.

jacobheun commented 4 years ago

The downsides to option 1 could be mitigated by adding the text to the commit message on a squash merge. The big advantage to this is that it's very easy to see the RFC along with the exact diff change of the spec. We also get a link to the github PR via the squash, which is nice for seeing any extra dialogue.

Stebalien commented 4 years ago

The downsides to option 1 could be mitigated by adding the text to the commit message on a squash merge. The big advantage to this is that it's very easy to see the RFC along with the exact diff change of the spec. We also get a link to the github PR via the squash, which is nice for seeing any extra dialogue.

Note: I believe the goal is to squash both the RFC and spec changes into a single commit. That way, they can all be viewed at the same time.

WRT context, I believe this is best captured with an alternatives/drawbacks section. Most feedback on an RFC falls into either of those categories (what if we did X, pros/cons).

jacobheun commented 4 years ago

Note: I believe the goal is to squash both the RFC and spec changes into a single commit. That way, they can all be viewed at the same time.

Right, the main issue is if the RFC is edited after the fact, which we should avoid. It's not hard to back track, just annoying.

I do think option 2 is preferable as it's easier for most people to consume the RFCs as standalone documents than commit logs, I just like the concrete change of the commit log.

raulk commented 4 years ago

@Stebalien

WRT context, I believe this is best captured with an alternatives/drawbacks section. Most feedback on an RFC falls into either of those categories (what if we did X, pros/cons).

I've added an "Alternatives considered" section in the proposed outline for an RFC doc.

@jacobheun

Right, the main issue is if the RFC is edited after the fact, which we should avoid. It's not hard to back track, just annoying.

RFC docs should only be edited after merging to incorporate errata -- and this would be trackable via git history.

chronaeon commented 4 years ago

Request for Comments = RFC Request for Change = RFC

Maybe the latter deserves a unique abbreviation.

lidel commented 4 years ago

I took a stab at RFC-0001: Text Peer Ids as CIDs using "option 2". Let's test and refine the process in https://github.com/libp2p/specs/pull/209

lidel commented 4 years ago

Our test RFC-0001 (https://github.com/libp2p/specs/pull/209) is getting positive reviews so far. What will be the next step in accepting/merging RFC?

Is there a designated spec custodian that makes the call, or do we require something like "at least three approving reviews from board members" ? Who is on the "RFC board"? Should any of this be time-bound?

jacobheun commented 4 years ago

I think the RFC framework should be added similar to https://github.com/libp2p/specs/blob/master/00-framework-01-spec-lifecycle.md and follow its lifecycle. We should also link to the RFC framework from there as a reference for edits to specs beyond Working Draft.

I would expect edits to an existing spec via RFC follow the timeline and approval strategy for its current stage (3A in the case of peer id).