EIPs

EIPs copied to clipboard

• Adds links RFC 822 and RFC 2119
• Adds rules to deal with RFCs

Change to EIP-1: See files tab

Hi! I'm a bot, and I wanted to automerge your PR, but couldn't because of the following issue(s):

---

(fail) eip-1.md

classification
updateEIP

• Changes to EIP 1 require at least 5 unique approvals from editors; there's currently 1 approvals; the remaining editors are @lightclient, @axic, @samwilsn, @micahzoltu, @gcolvin

(fail) eip-template.md

classification
ambiguous

• 'eip-template.md' must be in eip-###.md format; this error will be overwritten upon relevant editor approval

Huh, who knew? RFCs have spelling mistakes.

There is also a good argument for not copying RFCs. The RFC Editor maintains a canonical list at https://www.rfc-editor.org. For each RFC there is an Info page with TXT, PDF, and HTML renderings of the RTF and a host of information about the RFC. The RFC style guide at https://www.rfc-editor.org/info/rfc7322 requires that links to RFCs be to their Info page, not to a particular rendering. The required form is https://www.rfc-editor.org/info/rfc#. Why not just do as they ask?

@gcolvin Where in the style guide does it say that third parties referring to RFCs should not include the raw text?

@gcolvin Where in the style guide does it say that third parties referring to RFCs should not include the raw text?

@MicahZoltu It doesn't. It requires that links to RFCs be to their Info page, presumably because it is more informative.

https://www.rfc-editor.org/rfc/rfc7322.html#section-4.8.6.2

We are free to choose a particular rendering and copy it anywhere we like, but I am doubting that we should.

I am generally against enforcing the "no external links" decree on RFCs.

So here's my thought: we create a page that redirects to the specified RFC info page, while keeping text backups of the RFCs. If for some reason the info page dies, we can have it redirect to the text backups instead. How does that sound?

I think that solution is too hacky. It would require users either type the entire eips.ethereum.org/rfc-X url for links (which is in contrast of our current relative link policy) or we use relative links that are resolved only once the site has been deployed, meaning the links can't be accessed when viewing on github.

I guess an option would be to allow direct links to the RFC, but have the linter fail if a backup isn't made?

Why are we afraid of RFC links failing? The whole Internet is built to IETF Standards, and IETF Standards themselves use those links. They aren't going away.

What I would suggest is that we provide a Normative Reference section with full citations for both EIPs and RFCs, as is required by IETF for RFCs.

Why are we afraid of RFC links failing? The whole Internet is built to IETF Standards, and IETF Standards themselves use those links. They aren't going away.

This argument could be made for many links. By not allowing any external links, we avoid a lot of unneeded discussions. And after all, the internet could die...

What's the problem with linking to text-based RFCs? Yes, it might not be perfect according to their style guide. But I feel like keeping all information in the EIPs repository is worth the small tradeoff.

I'm pretty sure the style guide linked by @gcolvin above is specifically for people drafting RFCs, not for people referring to RFCs from elsewhere.

In the past we have discussed managing a whitelist of "acceptable" external links (like RFCs), but the challenge is in maintaining that list and dealing with people requesting that their thing be added to it. While RFCs certainly seem like an obviously right choice, it opens the doors to everyone claiming their standardization thing is also a right choice.

I think the primary difference here (including the RFC text in this repository) is that anyone can do this for any source of standard being referenced (assuming it is license compatible) and we don't have to get into the weeds about what each different standards committee's policy is on immutability and whatnot.

@MicahZoltu I'm pretty sure the style guide linked by @gcolvin above is specifically for people drafting RFCs, not for people referring to RFCs from elsewhere.

RFC 7322 includes guidance for how to refer to RFCs from within another RFC. They also have guidance for other types of references. I strongly advise that we follow their guidance. In essence

... The use of URIs in references is acceptable, as long as the URI is the most stable (i.e., unlikely to change and expected to be continuously available) and direct reference possible. ... Note that URIs may not be the sole information provided for a reference entry.

So like the IETF I just don't have a problem with the judicious use of external references, normative and informative. RFC 7322 itself has a lot of informative references. I don't find "we are afraid they might cause too much work in the future" a convincing argument for imposing unnecessary restrictions on EIP authors. Authors, reviewers, and editors can simply exercise good judgment, and if we can't get the resources we need to create high-quality documents we are in trouble regardless.

I also don't have a problem with putting an extra copy in our repo when we are allowed to. The citation in the Reference section can include both links. But of course that means being sure that we have the legal right to publish a copy, which creates its own problems. For RFCs we are sure we have that right.

as long as the URI is the most stable (i.e., unlikely to change and expected to be continuously available) and direct reference possible

For the purposes of the EIPs repository, the EIPs repository itself is the most stable and direct reference possible.

It's stable and direct, and also misses the full context of the Info page. I've suggested we put both the canonical link to the IETF and a link to our copy in the Reference section. And please let's use the HTML rendering of the RFC, which includes links to the other renderings and to the Info page.

And please let's use the HTML rendering of the RFC, which includes links to the other renderings and to the Info page.

I'd be okay with that.

It's stable and direct, and also misses the full context of the Info page.

If the HTML rendering includes links to the other renderings, then we're good, right?

@SamWilsn EIPW bug?

If the HTML rendering includes links to the other renderings, then we're good, right?

Good enough, thanks.

with all anchors replaced with internal anchors

What does this mean?

What does this mean?

By default, all the anchors in the HTML rendering of the RFCs have an "external" link to themselves before the anchor part.

with all anchors replaced with internal anchors

What does this mean?

By default, all the anchors in the HTML rendering of the RFCs have an "external" link to themselves before the anchor part.

So you are asking the EIP author to edit the links inside of the RFC?

Regardless, this is getting to be a lot more hassle than just linking directly to the canonical RFC Info page that the IETF maintains.

And regardless, this is getting to be (please forgive my annoyance) a silly level of paranoia about external links. But I'll need to bring this up at a more general level because - like the IETF - I don't in general have any problem with external links, and strongly object to our draconian policy.

The problem isn't that the EIP repository might outlive the internet. That's unlikely. What I do believe to be the problem is that the EIP repository might outlive the HTTP and HTTPS standards.

EIP repository might outlive the HTTP and HTTPS standards. I'm sorry, but that's exactly what I mean by silly paranoia. If HTTPS goes away the modern world will stop working, including our repo.

By outlive the standards, I meant that a new standard, say super-http-variant://, becomes the norm, to the point that even the IETF website has migrated.

There's the issue.

If the IETF migrates their website then every single RFC that refers to another RFC will need to be updated. And the many, many other links to the RFCs will be broken. And again, if HTTP changes that much then every link on the web would break. It's far more like that Github will go away.

So please, if insist on linking to our own copy let's just use the IETF's HTML rendering as it is.

The commit c4e94759e24df0edf2dff7f7f842449bc6c4a68d (as a parent of 025175f3a639d27325ed498c8132424440cfba60) contains errors. Please inspect the Run Summary for details.

The commit 2785e802a7ab7ef5997f87f28be467faa74d711d (as a parent of ac7438374b90a2ed7b99e07fde66a98dad1cf83a) contains errors. Please inspect the Run Summary for details.

Stahp!

FYI - this will need a manual merge from @MicahZoltu or @lightclient. Note that I have fixed the CI to not error in this PR, but the current CI will be failing regardless.

The commit 709121d390efe44a73f39385df3d1ac071651c98 (as a parent of d66baf42240c19b2af7bb2f4a42cf923b2c62a97) contains errors. Please inspect the Run Summary for details.