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 Create an EIP External Link Archive #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.

[xinbenlv]

Suggested change

	External resources are resources that are hosted outside of the EIPs repository. Links to external resources **MUST NOT** be included, except in `Living`, `Meta`, or `Informational` EIPs. External resources may disappear, move, or change unexpectedly.
	Links to external resources **SHOULD NOT** be included without justification over and mitigation against the following caveats:
	1. External resources may disappear, move, or change unexpectedly. Therefore, EIP should choose permlink or archive link over transient links/
	2. EIP is not meant for project-promotional purpose. Links to reference implementations or mentioning of projects outside of @ethereum org's repo **MUST** be justified based on merit by a consensus amongst the editor group.

[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

[xinbenlv]

Suggested change

	- Resources with an appropriate backup in the assets folder
	- Links to permlinks in any standard body that exists over 10 years, such as IETF, ISO, NIST, W3C,...
	- Resources with an appropriate backup in the assets folder

[Pandapip1]

This is outside the scope of this PR.

[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.

[gcolvin]

Suggested change

If you feel that a link you wish to include shouldn't violate the above rules, please submit a Pull Request to change them. Remember that the smaller and more specific the change, the more likely it will be accepted.

I don't think this needs saying. PRs are always welcome. Advice on what makes for a good PR applies to all of them.

[Pandapip1]

PRs are always welcome.

People don't realize that. You wouldn't believe the number of comments like "why is such and such a rule a thing, I would like to change it to XYZ." People are afraid of touching things that they think are hallowed or something. Stating explicitly that it is not sacred aids in removing that barrier.

[gcolvin]

Gotcha. In which case it needs saying, but as more general statement elsewhere in EIP-1. For that matter, people don't realize that they are always welcome to review PRs to any EIP.

[github-actions]

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.

[gcolvin]

I have asked for a change below and really want to see it or something close to it go in. But I'm approving this anyway.

[gcolvin]

Gotcha. In which case it needs saying, but as more general statement elsewhere in EIP-1. For that matter, people don't realize that they are always welcome to review PRs to any EIP.

[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.