Call for Input: RFC-like back-references?

[bumblefudge]

Call for Input

Decision: Should EIPs have backlinks in frontmatter (and display them on the other end when published)?	Some kind of simple to understand question where affirming/rejecting have clear (non-)actions.
If Affirmed	@bumblefudge will open a PR on EIP-1 adding updates and replaces to EIP-1 and the template, including an explanation that any author can use these without approval or consent from authors of updated/replaced EIP. [I could probably also volunteer to do a MVP of the forward-linking feature on the replaced/updated EIPs if it stays in jekyll but I'm sure others would do it better]
If Rejected	Status quo
Method	Rough Consensus
Deadline	February 7, 2024

Sorry I missed today's meeting! At previous meetings, I brought up offhand the analogy to IETF RFCs, which are about as "immutable" as EIPs are once they get finalized, and yet still manage to get updated and/or superceded routinely without modifying the updated or superceded RFCs. They achieve this not in the finalized documents themselves (which are, bit-for-bit, immutable in a txt format), but by the rendering of them in the IETF "Datatracker" (the functional equivalent of our EIP static site-generator pipeline, perhaps?).

Exhibit A: How IETF RFCs handle this:

This is what it looks like when you search for a superceded and/or updated RFC in datatracker:

(Src)

And this is how it displays at the canonical permalink for a given RFC that has been updated and/or superceded:

(Src)

Future RFCs that update or supercede ("obsolete") a finalized one simply mark themselves as such in frontmatter like so:

(Src, linked from here)

These back-references get picked up by the datatracker database and show up whenever the older RFC is displayed by it.

Exhibit B: How might the EIP process handle "updates" and full-blown supercessions?

I think we could introduce a frontmatter field going forward (before the WG processes diverge too much?) like IETF has for updates and/or obsoletes/supercedes. Since we are using a static site generator (or perhaps some day soon, various different ones!) to re-render the entire corpus of EIPs each time a PR is merged, this could allow the same functionality, where the HTML page you see when you hit a permanent link could contain "Updated by"/"Superceded by" links the minute an updating or a superceding EIP gets accepted.

Would this help mitigate the various discussions about how to update normative or semi-normative/substantive sections of final EIPs? It feels like the people trying to update final EIPs are quite underwhelmed by the recommended path of "just open a new one" since there's no forward link to these new docs from the old ones...

[bumblefudge]

Caveat implementor

Note that at IETF, there is no "change controller", meaning that anyone can open an RFC that obsoletes a prior one, and it's the responsibility of the WG ratifying that RFC to decide if author Bob is qualified to obsolete the work of author Alice. This is a non-issue most of the time since RFCs move through WGs that already decided Alice's work was worthy of updating and Bob was qualified to do it when they accepted the draft RFC as a work item... this might be where the analogy breaks down.

We might want to bikeshed updates/updated-by and/or obsoletes/supercedes to be more tentative reflecting the lack of a normative legitimacy to all proposals, like proposes-update/proposed-update and proposes-successor/proposed-successor ? Unless we want to get into complicated gymnastics about making Alice approve Bob's PR 😄

[SamWilsn]

@bumblefudge is this a fair distillation of your post down into a few questions?

Do we want to add an optional field to the preamble (possibly obsoletes/supersedes/updates/etc.) that contains a list of proposals that are replaced by the current proposal? If so, do we want to display a notice on those listed proposals that they've been replaced (with links to their replacements)?

---

Assuming my rewording maintains the spirit of your suggestion, I am in favour of doing both.

[bumblefudge]

Well, I guess my proposal was twofold, and the other half is kinda work i'm trying to trick you into signing up for, @SamWilsn 😅
1.) Add backlink frontmatter props to EIP1+template (including change controller constraints and/or caveats)
2.) Add forwardlinks to the backlinked docs in the publication pipeline 🌶️ 🌶️ 🌶️

I think this would be flexible enough to allow all kinds of follow-on docs without violating immutability, but I also suspect that without #2 it won't be very satisfying to the people proposing them in the various open PRs right now!

[SamWilsn]

Updated my comment!

[bumblefudge]

LFG

[shemnon]

I find @bumblefudge's caveat concerning, especially because "any author can use these without approval or consent from authors of updated/replaced EIP." I expect we will see people using it against other EIPs simply because they disagree with the design decisions of other authors. With the IETF process they at least need to gain the approval of the WG chair to add the change.

Could we add that it then requires consent of the EIP editors or authors of the referenced EIP to add a supercedes/updates tag?

[abcoathup]

I'm in favor (but don't have a vote)

[SamWilsn]

Could we add that it then requires consent of the EIP editors or authors of the referenced EIP to add a supercedes/updates tag?

Making this a permissioned field either:

• Puts EIP Editors in the position of having to decide (removing credible neutrality), or
• Gives authors the power to reject a perfectly valid replacement for non-technical reasons (eg. profit, competition, etc.)

I'll only support this field if it's permissionless, and the forward-links are something like:

Superseded by: 1234, 1235, 5432

Please note that any proposal may claim to supersede this one, and this list is provided for information only. These links may not be endorsed by the authors of this proposal or by the EIP Editors.

[shemnon]

I don't support the ability to obsolete an existing spec in a permissionless fashion. Even with the caveat it's a claim. But I'm not an editor.

[bumblefudge]

thanks to @abcoathup and @shemnon for weighing in! Valuable input.

If this took a "permissionless" form, I think there will still be a de facto distinction made by the EIP audience between "blessed" follow-ons and supercessions (e.g. adding one of the original authors as a co-author before going final) and totally independent or even antagonist ones-- I'm not sure the git process needs to formalize this, tho (it would, if nothing else, make for lots of editor headaches to be in the loop and having to act differently depending on whether a target-author has signed off "officially" or not).

Would it help to bikeshop the semantics? Maybe copy-pasting the IETF terms without bringing along the WG governance confuses the nature of the thing, and a more permissionless process would be implied by different terms?

original	alternative1	alternative2	alternative3	alternative4	help me out here guys
replaces	proposed-replacement	forks	challenges	vNext	???
replaced by	possible replacement	forked as	challenged by	vPrev	???
updates	proposed-addendum	extends	depends on	upstream	???
updated by	possible addenda	extended-by	downstream	downstream	???

[bumblefudge]

I don't support the ability to obsolete an existing spec in a permissionless fashion. Even with the caveat it's a claim. But I'm not an editor.

Well, technically, we already have this, and people propose upgrades or replacements for existing mechanisms all the time-- we we just don't have a mechanism for pointing to all proposed obsoleting EIPs from a given EIP! Which is why i'm so fixated on the exact mechanism by which backlinks get expressed as forwardlinks

[SamWilsn]

adding one of the original authors as a co-author before going final

With today's tooling, you do not need to consent to be added an an author.

[bumblefudge]

backstory/rabbitholes here

[g11tech]

after thinking about this issue: i am opposed because if this is permissionless (and permissioned doesn't make sense as mentioned by @SamWilsn ) its a spam vector for people to suggest "updates" on popular EIPS (and hence can never be permissionless because editor might be forced to evaluate the worthiness of the update in accepting the updating EIPs)

[SamWilsn]

@g11tech are you worried about completely useless proposals cluttering up popular ones, or legitimate-but-unlikely-to-be-adopted proposals doing it?

[g11tech]

@g11tech are you worried about completely useless proposals cluttering up popular ones, or legitimate-but-unlikely-to-be-adopted proposals doing it?

Completely useless can be weeded out, it's the second category but we only activate the forward link when the proposal is adopted? (for EIP driven by ACD it might make sense, for ERCs and RIPs where it might not)

[SamWilsn]

How would you feel about giving it a try for some fixed period (say a year) and see how much crap accumulates?

[bumblefudge]

@g11tech Thanks for the feedback, I actually agree that docs getting to final but never being adopted look bad and should be considered a form of misincentive/abusive traffic for the process. I just disagree that linking between documents affects it significantly.

I would actually argue that "unlikely-to-be-adopted" ERCs (e.g. at the SC/Wallet layer where there is never a binary adoption decision like the ACD upgrade schedule) pose a serious problem for catherders and future EIPIP proposals should address them-- I just doubt that giving spam EIPs a link-forward mechanism would actually make more of them be written. I also think we should not punish the authors of valid BCP or security update documents (which no one is submitting because they have no guarantee that their target audience will ever see them) by depriving them of valid traffic & eyeballs just to avoid the ERCs which are less valid getting traffic and eyeballs.

I would recommend we adopt this linking mechanism ASAP for the benefit of giving a clear recommendation to people doing BCP and security addenda, and then turn our attention to the relationship between documents and adoption at the SC/Wallet layer, which is a bigger problem and unlikely to be solved by any tweaks (or lack thereof) to the document process or its publication tooling. I would volunteer to do a little poll/audit a year from now to have hard numbers on how many times it was used "for good" versus for cheap self-promotion/SEO, because maybe I'm wrong and this will throw open the floodgates of unnecessary single-implementer ERCs!

[bumblefudge]

(Spoiler alert: I think Solidity Summit and Wallet Working Group could maybe be directing traffic and discouraging "frivolous" ERC proposals to create something like an ACD equivalent at higher levels of the stack. But that's off-topic here, I would argue?)

[bumblefudge]

after discussing on EIPIP today, I feel more strongly than ever that some form of "replacement"/mutually-incompatible-version semantic is worth keeping. "fork" seems to encompass both the ACD categories (mapped to specific hard forks) and the ERC category (at the app level, replacements are forks, whether "friendly" or not)...

[SamWilsn]

The spirit behind forks: 1234 is great, but practically, I think it would cause a ton of confusion for authors.

[SamWilsn]

@g11tech:

As long as the clutter can be managed, I am fine with it.

@gcolvin:

For mainnet, it just happens automatically. The main purpose of having superseded would be to stop implementers from implementing an out-of-date proposal. I can see a need for it, but I'm not quite sure whether we want to do it this way.

[SamWilsn]

I don't feel like there is a consensus to move forward (I'm the only one strongly in favour) with this as proposed, but I also don't feel like there's opposition to the fundamental idea—just concerns about permissionless spam.

If we go ahead with Working Groups, I think that kind of structure may be more friendly to supersedes. For now, however, I think we should close this and not make any changes.

[gcolvin]

As happens too often I notice the closing of an issue too late, but I agree with the outcome.

If even some parts of an EOF go in there will be code that used to be OK to put onchain which no longer passes validation, at which point an EIP might in some sense be superseded or obsolete -- we can cross that bridge when we come to it. But any EIP that went onchain can never be totally obsolete, as it specifies behavior that has to keep on working for old contracts and for code dynamically generated by old contracts..

When a WG has taken responsibility for an ERC then an earlier ERC can be superseded in the sense that it is no longer, in their judgement, best practice. And for things like RIPs, where I understand the main purpose is assuring interoperability, then it definitely makes sense to indicate whether new RIPS are compatible with old ones. Again, we can cross that bridge when we come to it.

In all cases the WGs themselves will need to be part of the consensus.