Advise against external links & add myself as an active editor

[SamWilsn]

External links aren't durable, and may not necessarily permit redistribution. Some links may be durable and permit redistribution, but determining which links are/do is a subjective and onerous task for editors.

That said, I've chosen SHOULD NOT over MUST NOT to allow for special cases.

Note to editors: Signal approval with a comment, just in case the bot auto-merges on approval.

[eth-bot]

All tests passed; auto-merging...

(pass) eip-1.md

classification
updateEIP

• passed!

[MicahZoltu]

My name is Micah, I support this change.

[gcolvin]

I think external references should be rare but not forbidden. So I think we need to be clear about when and how to break the general rule. Normative links should of course not be a problem -- they are logically part of the specification. Informative links should be used rarely, and sparely even so. One link often suffices to put a specification in context.

When external links are used, they should be as authoritative and stable as possible. When stable links are unavailable consider adding the page to the Internet Archive or adding its contents to assets . A proper References section will be needed for external links, which would also serve to mitigate link rot. The references should follow same format that we use for our own EIPs.

[MicahZoltu]

My issue with having a fuzzy process like you have described @gcolvin is that we don't currently have enough active editors to keep up on it and do the necessary due diligence for what is acceptable and what isn't. On average, I would guess that every EIP contains 1-2 links initially (before I review it), and I think requiring editors to review every single one of these is too much of a burden. On top of that, I have found that when you point at a fuzzy rule for the reason for not allowing something the authors tend to question it/fight back and you have to engage in what usually is a very long debate about whether "A tweet or Reddit post on Internet Archive is an allowable link".

[SamWilsn]

I think external references should be rare but not forbidden.

I agree. I can imagine some cases that might require an external link (ex. to a large dataset) and straight up forbidding them is probably not the best idea. To that end, I've used SHOULD NOT in this PR, and not MUST NOT so that editors have some leeway in how this rule is applied.

So I think we need to be clear about when and how to break the general rule.

Also agreed, though I don't think we need to formalize those rules today. Plus, like @MicahZoltu said, the more complex the rules, the more work it creates for editors.

When external links are used, they should be as authoritative and stable as possible.

Determining which sources are authoritative and stable is definitely an undertaking. Should the Internet Archive be considered stable, even considering they've been sued by book publishers in recent history? What about IPFS links? External git repositories?

Plus there's the issue of licenses. Theoretically, I would like any random user to be able to take a backup of the EIPs repository and carry it around on a USB stick, and to be able to share that content with anyone else. EIPs themselves are CC0-1.0, so that isn't an issue, but external links can be any license, adding to the complexity for editors.

[gcolvin]

Note: I'm happy to merge this PR as is and make my own for the further changes I'd like to see.

I've used SHOULD NOT in this PR, and not MUST NOT so that editors have some leeway in how this rule is applied.

I agree with that.

... I don't think we need to formalize those rules today. Plus, like @MicahZoltu said, the more complex the rules, the more work it creates for editors.

About all I have in mind is the distinction between normative and informative references and the format of the References for outside links. I can't see formalizing more than that.

Determining which sources are authoritative and stable is definitely an undertaking

For normative references it's not that hard -- these are published standards, and the publisher generally maintains a stable web site. For informative references it's more work but also not such a big deal if the link rots -- the spec remains complete, just harder for some readers to understand. And having a proper References section means that searches for title and author will often resolve the broken link. (And yes, in general, don't copy stuff to assets that we haven't the right to republish.)

[gcolvin]

I'd suggest changing "external resources" to "non-normative external resources."

[axic]

How was this merged after a single approval? 😅

[SamWilsn]

How was this merged after a single approval? sweat_smile

I think I counted as an approval.

[MicahZoltu]

ethereum/EIP-Bot#53 (comment)