Update EIP-1: Expand External Link Policy

[Pandapip1]

I used to have a small description of the changes here, but I removed it. Just look at the Files Tab.

[eth-bot]

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 @axic, @samwilsn, @lightclient, @gcolvin

[xinbenlv]

Thanks for the PR. @Pandapip1 . I apprecitate it.

My stance is

1. I am in strong objection to changing SHOULD to MUST for external link prohibition. I don't think it brings more benefit than harm.

2. I am in weak favor of including consensus-spec to allowlist that doenst need a SHOULD justification. "favor" is because I really think consensus-spec is an essential part of EIP reference realm. "Weak" is because I worry there would be a tendency to strenghten the censorship once we have long allowlist.

I am open to be convinced and would follow the consensus amongst others.

[poojaranjan]

IMHO, we can shift our focus to "external" more than a "link".

I will be in favor of defining "external link" in EIP-1.

IIRC, "the external links policy" was brought in to discourage authors of Standard Track - ERC proposals to add link to their project in the proposed EIP. It may not be the same as using different repo link from the same organization.

Reference to link within the same GitHub organization shouldn't be considered as "external".

[xinbenlv]

IMHO, we can shift our focus to "external" more than a "link".

I will be in favor of defining "external link" in EIP-1.

IIRC, "the external links policy" was brought in to discourage authors of Standard Track - ERC proposals to add link to their project in the proposed EIP. It may not be the same as using different repo link from the same organization.

Reference to link within the same GitHub organization shouldn't be considered as "external".

@poojaranjan IIRC I remember there are two orthogonal reasons for our external link policy

1. To avoid using EIP for project promotional purpose.
2. To avoid link to useful but not persistent documents, this is being addressed by 10y rule and #5408

For avoiding promotional purpose, I think even mentioning project names unnecessarily without a link are considered harmful. For avoiding outdated link, I think even the same github organization of@ethereum shall be linked with caution: If a @ethereum project is not meant to be permanently preserved, a preservation effort to that link should be made, it also shall avoid link to a live changing document but rather a snapshot

[xinbenlv]

@Pandapip1 Once we have a consensus, in addition to update to EIP-1 to reflect that rule change, I also propose creating a informational EIP to lay out the reasonings why we impose these policies. EIP-1 shall be concise and act as a "spec" of process, the rationales also be preserved, and an informational EIP can serve the purpose.

[Pandapip1]

I am in strong objection to changing SHOULD to MUST for external link prohibition. I don't think it brings more benefit than harm.

I think that links must be treated as though they may disappear at any time. I have added a clause (requires a valid backup in the assets folder) that should fix that primary issue.

The other issue with external links is that unless they are actually part of the specification, reference implementation, or test cases, they often turn the EIP into 65% history lesson and 35% important stuff, which we want to discourage.

These small hurdles (e.g. requiring the link to be in the assets directory) are intentional. If it's not worth going over the hurdle to get the link in, well, then, you shouldn't have the link in there. If it is worth going over the hurdle (e.g. reference implementation), then the link should be allowed.

I hope that makes sense.

To avoid link to useful but not persistent documents

There were two other justifications you missed:

3. External links might change their content, causing the EIP to be interpreted differently
4. One MUST be able to accurately reconstruct Ethereum from just the EIPs repository in a million years if someone stuck a copy in a time capsule

[SamWilsn]

I am firmly against allowing most, if not all, of these links.

I am also against changing the wording to MUST instead of SHOULD. Yes, eipw strictly enforces the rules, but we can still override it when necessary.

[lightclient]

@SamWilsn I think manually override for final EIPs is okay, but for EIPs still being actively worked on - we should just add ethereum/consensus-specs to an allow list in EIPW so that we don't need to manually merge each of their updates.

[xinbenlv]

I am in strong objection to changing SHOULD to MUST for external link prohibition. I don't think it brings more benefit than harm.

I think that links must be treated as though they may disappear at any time. I have added a clause (requires a valid backup in the assets folder) that should fix that primary issue.

The other issue with external links is that unless they are actually part of the specification, reference implementation, or test cases, they often turn the EIP into 65% history lesson and 35% important stuff, which we want to discourage.

These small hurdles (e.g. requiring the link to be in the assets directory) are intentional. If it's not worth going over the hurdle to get the link in, well, then, you shouldn't have the link in there. If it is worth going over the hurdle (e.g. reference implementation), then the link should be allowed.

I understand where this stance come from and knowledge it has merit. But I disagree it's a small hurdle. Copy content to ethereum/EIPs require the content to be properly licensable, (e.g. as we see IETF unsure for file before 19X0) or it renders differently, e.g. RFC in txt or html.

Imagine there is another blockchain (e.g. BIP) adopting the same no-external-link rule trying to reference ERC-721, and EIPs impose a rule of "copier must release their patent right", it might mean BIP cannot copy ERC-721. I think therefore allowing the links' benefit overweight they might disappear.

I'd argue instead that if we, the EIP editors, worry enough that a link may disappear, we shall bear more fraction of the burden of preservation. and that's why I was working on #5408 an ExternalBot myself

I hope that makes sense.

To avoid link to useful but not persistent documents

There were two other justifications you missed:

3. External links might change their content, causing the EIP to be interpreted differently

1. Even EIP is not completely unchangeable, such as 712 in the question. Should this rule apply, this rule can rule out EIP referencing EIP itself or another EIP.
2. It can be solved by archive service e.g. IPFS or permlink.

4. One MUST be able to accurately reconstruct Ethereum from just the EIPs repository in a million years if someone stuck a copy in a time capsule I know it's a goodfaith goal, I disagree with this generalization. I don't think it's useful and feasible. Unless we want to include a full English dictionary and Wikipedia in asset file plus the whole Google index search engine. We can't explain what blockchain is, what merkle-tree is, what ECDSA or AES is. Or when new things come, we can't explain BLS12-381 or Beacon Chain in EIP. It's just not feasible to consider EIP an isolated island without considering the whole Ethereum movement and existence of internet. We have to draw a line somewhere.

[SamWilsn]

@SamWilsn I think manually override for final EIPs is okay, but for EIPs still being actively worked on - we should just add ethereum/consensus-specs to an allow list in EIPW so that we don't need to manually merge each of their updates.

I'd be fine permitting ethereum/consensus-specs if the links are to an exact commit.

[Pandapip1]

I am also against changing the wording to MUST instead of SHOULD. Yes, eipw strictly enforces the rules, but we can still override it when necessary.

I would prefer to be explicit. If there's an external link they want to include, then they can submit a PR adding to this list, and we can debate the merit

[SamWilsn]

I am strongly against any policy that allows links to mutable resources. I'd even possibly argue for removing discussions-to from final proposals.

I am fine with links to files in a specific commit in execution-specs and consensus-specs, since they are explicitly specification repositories, and git commits are immutable. There's still a slight data availability problem, but I think that's fairly minor. I am not fine with links to issues, PRs, wikis, or any other GitHub specific features.

While links to go-ethereum could satisfy my immutability requirement, I'd argue that the go-ethereum codebase is not acceptable for specifications. It's a fully production-ready client, and is not written with readability as a primary motivation.

[gcolvin]

I simply don't agree with the demand for total immutability of links, or prohibition of links outside of such a narrow scope. And I keep being too busy to discuss it much. My own preference remains to stay closer to the IETFs approach, as laid out in the RFC style guides. See https://www.rfc-editor.org/styleguide/ and https://www.rfc-editor.org/styleguide/part2/

Simply put:

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. The URI will be verified as valid during the RFC editorial process. https://www.rfc-editor.org/rfc/rfc7322.html#section-4.8.6.1

Importantly, they do insist on an actual list of References at the end of a document, both Normative and Informative. The References need not even contain a URI, but should contain authors, title, publisher, date and such to unambiguously refer to a document and find it somewhere if the URI changes. (Search engines exist. Libraries exist. If they stop existing, who will care about rewriting Ethereum from scratch?)

And they are of course stricter about Normative References. So, for instance, references to other standards are OK. E.g.

Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., Yergeau, F., and J. Cowan, "Extensible Markup Language (XML) 1.1 (Second Edition)", W3C Recommendation REC-xml11-20060816, August 2006, http://www.w3.org/TR/2006/REC-xml11-20060816.

But, for instance, references to Web repos are OK only for Informative References, but still should be as precise as possible. E.g.

“Python implementation of SAML2”, commit 7135d53, March 2018, https://github.com/IdentityPython/pysaml2

[xinbenlv]

I strongly agree with @gcolvin's stance in link policy.

I think mandating full immutable links is not only unnessary, but also hurting the usefulness of EIP as whole. Archiving can solve mutable content problem. Wikipedia solves it by just having an archive bot to ensure anything linked gets archived.

[Pandapip1]

The point here is that users shouldn't have to Google to find things. A user should not have to rely on external information in order to implement a standard - that defeats the purpose of having a standards repository!

The current rules as put forth in this EIP are hopefully an acceptable middle ground. Doing ctrl+p, Save as PDF, and Upload Files hopefully aren't too onerous. If assets being CC0 is the blocker here, I would be more than willing to collaborate with @SamWilsn to fix that issue.

[gcolvin]

A user should not have to rely on external information in order to implement a standard - that defeats the purpose of having a standards repository!

The IETF maintains the repository of Standards on which the internet it is built. The RFCs do not pretend to be complete unto themselves, and have always allowed both Normative references to outside Standards and Informative References to the open literature. They don't copy outside documents into their repository. They don't even require links.

[xinbenlv]

The point here is that users shouldn't have to Google to find things. A user should not have to rely on external information in order to implement a standard - that defeats the purpose of having a standards repository!

The current rules as put forth in this EIP are hopefully an acceptable middle ground. Doing ctrl+p, Save as PDF, and Upload Files hopefully aren't too onerous. If assets being CC0 is the blocker here, I would be more than willing to collaborate with @SamWilsn to fix that issue.

As i reiterate above, i strongly object to "no external links" policy.

In this on argument, for example, when you say PDF, what is PDF? If you think this might be a joke question, just imagine someone visiting eip.ethereum.org might need to learn from "git", "JSON", "URL" to new concept like "IPFS", "Arweave", BLS12-381. What confident do we have to think EIP repo is encylopedia？

Also copy and paste of something that was not originally CCO is absolutely a violation of CCO.

I think EIP is a collaboration. May I suggesr surveying authors before making a controversial policy is probably a good idea.

[gcolvin]

Once upon a time EIP-1 was considered mostly in the "should" category. At the editors' discretion authors could be given a lot of leeway. Anyway, here is one of the world's most important RFCs and an example of external references: RFC 9112 HTTP/1.1. The normative references are mostly to other RFCs, with some exceptions:

American National Standards Institute, "Coded Character Set -- 7-bit American Standard Code for Information Interchange", ANSI X3.4, 1986.

Welch, T., "A Technique for High-Performance Data Compression", IEEE Computer 17(6), DOI 10.1109/MC.1984.1659158, June 1984, https://ieeexplore.ieee.org/document/1659158.

The first exception is the specification for ASCII. It has no URI because ANSI does not publish online. I wasn't able to quickly find a free copy online. Unfortunate, but HTTP needs ASCII. The other exception is the paper in the open literature that describes LZW compression. It's not peer reviewed. It's not even a standard. Unfortunate, but HTTP needs LZW. The link is to the IEEE's site, but the PDF there is paywalled. Google, Duckduckgo, and Bing all found free PDFs. For both of them you could to go to a good library. This is the real world.

[github-actions[bot]]

There has been no activity on this pull request for 2 weeks. It will be closed after 3 months of inactivity. If you would like to move this PR forward, please respond to any outstanding feedback or add a comment indicating that you have addressed all required feedback and are ready for a review.

[Pandapip1]

Still an issue.

[kdenhartog]

Might I suggest the usage of markdown reference links as the primary method of linking as well? Doing it in this way allows for a Bibliography section to be created at the bottom of the document.

[Pandapip1]

Might I suggest the usage of markdown reference links as the primary method of linking as well?

There's a markdown linter option for that. We can discuss enabling it.

As for the bibliography section, I agree that it is a good idea. It would be a pretty significant change to EIP-1, so it would take a while to reach a consensus.

I propose APA-v7-style bibliographies.

[SamWilsn]

What's your preference @Pandapip1 between this and #5757?

Personally, I'd like to close this PR and open a similar one when we have the sources policy merged.

[Pandapip1]

My personal preference is this PR; I would prefer a single document with all the policies. Nonetheless, I like the modularity of your approach from the standpoint of getting things approved using an existing workflow, even if it makes finding the relevant rules much more challenging.

[SamWilsn]

EIP-1 would still have the authoritative list of permitted sources

[lightclient]

Closing as we've decided to go with the 5757 approach.