# Pros and Cons for Allowing External Links in EIP.

Readers: please feel free to edit this doc!

## Test our consensus
Can EIPs link to?

### Direct
- Another EIP
### Technical Specs of Ethereum
- A commit of https://github.com/ethereum/yellowpaper

### Discussions of Ethereum
- issues or pull request under github.com/ethereum/EIPs
- Link to the same EIP's `discussion-to` on https://ethereum-magicians.org
- Link any thread of https://ethereum-magicians.org
- Link any thread of https://ethresear.ch

### Other online standards
- A final DIP of Devcon
- A final BIP of Bitcoin
- A final PIP of Python
- A final IETF RFCs
- A final ISO standards

### Books and Paper
- Link to a copy of Paulo S. L. M. Barreto, Ben Lynn, and Michael Scott. Constructing elliptic
curves with prescribed embedding degrees. In Stelvio Cimato, Clemente Galdi,
and Giuseppe Persiano, editors, SCN 02, volume 2576 of LNCS, pages 257–267.
Springer, Heidelberg, September 2003.
- Link to a copy of A published printed book, e.g. Zimmermann, Philip (1995). PGP Source Code and Internals. MIT Press. ISBN 0-262-24039-4.

### Etheruem's organizational repo
11. A commit of https://github.com/ethereum/go-ethereum
12. A commit of https://github.com/ethereum-cat-herders
13. A commit of https://github.com/ethereum/solidity
14. A commit of https://github.com/ethereum/aleth
### Etheruem's ecosystem
16. A commit of https://github.com/MetaMask/metamask-extension

## Reasons for MORE restriction:
- Links might rot or change contents
- Pretty bad case: An expired domain is bought by a scammer, and we send users directly into a phishing scam
- Links can just be ommited
- If need be, they can be placed in the assets folder
- Could even be done by a bot automagically
- EIPs should only ever depend on information in the EIPs repository
- Imagine if EIP-20 required you to read Adam Smith's The Invisible Hand
- Links would have to be `nofollow` to comply with Google search policies and other standards
- Solution: Requires a custom Jekyll renderer
- Avoid using EIP as a spam / advertising place for business and conflict of interest.

## Reasons for LESS restriction:
- Allow referencing other standards to give complete technical spec, e.g.
- EIP-5593 references W3C standard of "secure origin"
- EIP-XXX references a consensys-spec
- EIP-5289 references Base64

- Avoid copying content that's prohibited or restricted by their copyright licensing
- originally copyright license granted in MIT https://github.com/epsproxy/eps-contracts/blob/2888dc69da09a926f544749f908586f0a8a39c5d/contracts/EPS.sol#L1
- but was modified by this commit, but committer was not an copyright holder https://github.com/ethereum/EIPs/commit/792b7d65c73171402314d074ea71893b1d42afe4

- Avoid error in copy-pasting or duplicates, following the principle of Don't-Repeat Yourself(DRY)
- imagine if ASCII table needs to be copied everywhere,

- Allowing the content to be updated and corrected in the original
- EIP-712 is an example

- PDF copys of HTML pages don't properly follow fragment URL parameters to link to a specific normative definition
- For example, linking directly to a "potentially trustworthy origin" would be done with https://www.w3.org/TR/secure-contexts/#potentially-trustworthy-origin where as this doesn't seem possible to do when linking to a PDF because of how github renders them.

_Originally posted by @Pandapip1, @Xinbenlv in https://github.com/ethereum/EIPs/issues/5597#issuecomment-1237535407_

## Requirements for Link Policy

> I'm just throwing these requirements in here. If you feel that something I put in "Nice to Have" is actually a "Must Have", move it! I would ask that we not move things out of "Must Have" without discussion. - @SamWilsn

### Must Have

* Final/Withdrawn EIPs cannot substantially change. This extends transitively through links.
* EIPs and referenced resources remain available forever.
* EIPs and referenced resources required for implementation are widely available (and preferably redistributable) at no cost.
* Differentiates between "required for implementation" (normative) and "contextual" (non-normative) references.

### Nice to Have

* Allows referencing non-HTTP resources (like books, periodicals, and papers.)
* Broken links in final EIPs can be updated via a defined errata change that registers the errata in a table at the bottom

## Proposed solutions
### Proposed solution 1 By @xinbenlv
1. Establish the principles that
- authors shall make their best effort to obain the link to its most stable snapshot of a reference, excepted for exempted sources
- links shall not be promotional, subject to editor judgement, except for exempted sources

2. Pre-approved sources
- EIPs
- Etheruem Specs
- Yellow Paper
- consensys-spec
- (TODO add other ethereum spec)
- IETF/W3C standards (TODO add more standard to allowlist)

3. Adding links from pre-approved and non-pre-approved sources
Also, any editor is allowed to add new standards that exists for 10y or above to this list
to remove a source or to add any source less than 10y or not a standard body, requires an consensus in the editor group.

- For any pre-approved sources, they MAY be referenced by Author at their sole discretion.
- For any non-proapproved sources, when referencing the links, Authors MUST provide a rationale of why this source is necessary here in the text around. Editors or other Author's Peer MAY advise a different source for stability or avoid promotional, and MAY veto if deemed promotional or unrelevant.

4. Infra improvement
- Update the EIPW and other markdown lint to detect pre-approved source and warn non-pre-approved sources.
Authors can provide markdown lint suppress to suppress a warning
- Update the archive bot to archive external link at the snapshot.

### Proposed solution 2 By @Pandapip1

External links are allowed, but before the EIP is merged, we have a bot that automatically converts them to PDFs and sticks them in the assets folder. Then, the EIP is modified to reference those PDFs automatically. For these PDFs, a `Link: <URLHERE>; rel="canonical"` HTTP header is sent along with them. This would be the most technically challenging solution, but probably the one that would strike the best balance between immutability and being able to reference external works.

> I don't think such a solution is feasible, at least not in the general sense. How do you know if a resource allows redistribution (like copyright)? Assuming the resource does allow redistribution, how do you know where to stop crawling&mdash;just the linked page, links off the linked page, etc? I do like the `canonical` idea though, and if we mirror anything, we should add a `<link>` tag or header. - @SamWilsn

Copyright would probably not be an issue here. We could reasonably claim fair use:

- We significantly transform the copyrighted material (EIPs are very distinct from non-normative articles)
- E.G: "Use of a quotation from an earlier work in a critical essay to illustrate the essayist’s argument is a classic example of transformative use." (https://ogc.harvard.edu/pages/copyright-and-fair-use) is fair use :)
- Also: "Courts have also recognized, however, that non-transformative uses may be socially beneficial, and that a use does not have to be transformative to support a finding of fair use." (https://ogc.harvard.edu/pages/copyright-and-fair-use)
- Finally: "The two main considerations are whether the work is published or unpublished and how creative the work is." (https://ogc.harvard.edu/pages/copyright-and-fair-use) - all works that would be referenced would be published works (duh)
- We use it noncommercially (not a requirement, but aids a lot)
- We require authors to include as little links as possible
- The effect on the market for the work is none, since we require that all links be available for free

> As far as I understand your proposal, the only "transformation" we'd be performing on linked resources would be to convert to a PDF. I don't believe that's sufficient to qualify. There's also the issue that Fair Use is a US specific thing (eg. here in Canada, we have Fair Dealing.) I don't want editors bogged down trying to establish whether we can archive links as part of the editing process. - @SamWilsn

The "transformation" would be the EIP, and the "minimum amount" would have be the entire article (as it is important that the context does not change). Again, these are judged on a case-by-case basis, but:
1. The EIP repository and EIPs in general are a public service run for the world, offering free technical specifications out of the goodness of the hearts of the authors and editors. It would be extremely hard to make the case that we were claiming someone else's work *as our own* ***for our gain***
2. It would be the EIP authors that committed copyright infringement in the extremely unlikely case that it's deemed so (literally - the commit username & email would be that of the PR author).

### Proposed solution 3 By @SamWilsn

Here's an off-the-top-of-my-head sketch of what I'm thinking for a longer term external links policy:

- If the EIP is implementable without the link, remove the link.
- If we can legally include† the resource, put it in assets.
- If no immutable way to reference the resource* exists, remove the link.
- If the source has a proven track record of availability‡, allow the link.

At no point should we allow links to paywalled resources.

†: We'd need to maintain a list of whitelisted sources that can be included. Changing the list should require a pull request, approved by editors.

*: We'd need to maintain a list of URL patterns (and pick a token for books, maybe ISBN). Changing the list should require a pull request, approved by editors.

‡: We'd need to maintain a list of whitelisted sources that have a track record of availability. Changing the list should require a pull request, approved by editors.

## Proposed solution 4 by @gcolvin

Confession -- I haven't time this moning to do more than skim the above, only to (re-)state what's important to me.

In general -- many of the rules really should be just guidelines, trusting the authors, editors, and peer reviewers to use their best judgement.

Distictions --
* The World vs. The Internet
* Reference vs. Link
* Normative vs Informative
* Specification vs. Motivation/Rationale

References are to documents in the world, many copies of which may exist in various media. Links are to whatever happens to resolve their on the internet, if anything. Not all references even have links. Thus my demand that outside references be full citations, not just links. And of course, our requirements that links be of the highest available quality.

Only the Specification is Normative. Only Normative links should be *allowed*, and where needed they are *required*, even if they otherwise are not of good quality, even if they are paywalled online, and even if they aren't online at all.

The Motivation and Rationale are *not* Normative. They should contain no Normative references. If we truly wanted EIPs to be pure specifactions those sections woud not exist. But a proposal is not just a specification. It's an argument by the author that something should be done, and done in a certain way. it's explicitly *not* the editor's job to police the content of the argument.

Even technically an Ethereum client spans a number of disciplines: cryptography, protocols, databases, virtual machines, game theory, economics, and more. It's a rare developer who can master all of those. The real-world contexts for EIPs can span an even wider range and EIPs can be important to a wide range of readers, many (even most) of whom will read _only_ the EIP and (maybe) what it refers to. We need to let the author address and educate their auduence as they see best, including by using outside references. (E.g. saying that, "People need X" is less useful and convincing than saying, "As evidenced by <reference> people need X

## Proposed solution 5 by @SamWilsn
https://hackmd.io/@SamWilsn/H1dI_tOzj

## Rationale

### Why I suggest we don't ban non-free sources (xinbenlv@)
First published on https://github.com/ethereum/EIPs/pull/5757/files#r989694362

This is a very good intention. _Rhetorically_ with the similar good intent, can we ban all links to any content cannot be run without a hardware (e.g. computer or phone) that is not free, or can we ban all links to any content that is centralized, such as Github?

That's just a friendly joke, my real intention is to respectfully suggest not fully ban non-free content but require author to use a cheaper permissible sources whenever available.

Rationale

Even Wikipedia didn't make this requirement. I think this reduces our ability to link to useful content.
At the end of day, everything charges. We might live in a first world country that getting online is not very expensive, but my phone bill is 30 dollars a day, meaning if it take me 1 minute to find the link to my EIP online, I am charged by my phone ISP for 0.00001157407 for me to access the EIP I authored. I am saying, there is nothing free.

Also "free" is never free, you might be paying for ads, paying for your privacy or atttention.

That's why I suggest instead of requiring free access (because )