EIP editors should explain the external link policy to new authors

[xinbenlv]

trafficstars

Proposed Change

Dear editors, here is an example of comment that I like to suggest against:

No external links

There is nothing personal, I am just trying to voice suggestion against such editorial practice.

I suggest EIP editors avoid leaving a simple comment like this above, especially towards new authors who don't necessarily know how to challenge editorial comment.

Please note that, per EIP-1 shows the current policy in EIP-1

Links to external resources SHOULD NOT be included. External resources may disappear, move, or change unexpectedly.

Which is "SHOULD NOT" but not "MUST NOT" pursuant to RFC 2729 Please kindly allow authors to understand it's ok for them to include links when necessary given the current policy.

I am making it a EIP issue so I can easily reference in other of my comments.

I also think it's good for an Editor to set a good example about following EIP-1, and about understanding of "SHOULD" vs "MUST" in their editorial contributions

FYI: @axic, @Pandapip1, @gcolvin, @lightclient, @SamWilsn if my understanding of the current policy is incorrect.

[Pandapip1]

The current policy is that all external links are prohibited.

[xinbenlv]

I think that's a misinterpretation. Per https://github.com/ethereum/EIPs/commit/3062736369de16dd01acb9cdc5ea21757f9a994f It says "advise against external links" https://github.com/ethereum/EIPs/pull/4872#issuecomment-1060027445 @SamWilsn

[Pandapip1]

Again, the current policy is that all external links are prohibited. "Advise against" in this context means "warn authors that their EIP will not be merged until the offending link is removed."

[xinbenlv]

@Pandapip1 we share drastically different view on this. I heard you and I think you heard me too. Let's wait for other editors to comment.

I think authors shall be welcomed to share your views too.

[Pandapip1]

Superseded by https://hackmd.io/ddolKJF9TpGbO5MktrtT5A ~~Let me summarize the points as I understand them from both sides.~~

~~More restrictive:~~

• ~~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 omitted~~
  • ~~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~~
  • ~~Requires a custom Jekyll renderer~~

~~Less restrictive:~~

• ~~Easier to write an EIP~~
• ~~Adds context that might otherwise be missing~~

[Pandapip1]

Didn't mean to close, sorry.

[kdenhartog]

Here's an argument to advocate for the less restrictive approach.

I think there's major advantages to being able to reference other works externally and my interpretation of SHOULD NOT was that unless there's good reason to externally link, such as to reference another spec that's being normatively linked to, then it "should not" be done.

If the intent is to never externally link then this language should probably be updated to "MUST NOT".

With that in mind, I think should not is the right call here if you're intending to standardize technical specifications. I believe this is the intent with something like "standards track" available.

Many organizations like ISO/NIST/W3C/IRTF/IETF/OASIS are able to achieve good practices of linking as well for standards too, so I don't believe this is an impossible task.

With those considerations in mind, I would say there's good intention that this repository is not meant to contribute proprietary designs, IP encumbered material to create moats for for profit companies, or turn it into a thinly veiled sales tactic for companies to design a piece of technology and promote it through EIP standards. That kind of defeats the purpose of a standard in the first place.

So I do believe there should be limitations here, but I don't think saying no links strikes the right balance here.

Here's some ideas of how we might be able to solve this.

1. Use reference links so it's easier to spot broken links

2. Allow a select set of URLs that can be trusted to maintain documents for long periods of time like SDOs to be linked.

3. otherwise require the web page to be snapshot and linked through the internet archive time machine or pinned to IPFS maybe.

[xinbenlv]

Let me summarize the points as I understand them from both sides.

More restrictive:

• 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

  • Requires a custom Jekyll renderer

Less restrictive:

• Easier to write an EIP
• Adds context that might otherwise be missing

Thanks for starting this @Pandapip1 . I think it's a great way to coverage to a consensus.

I started a collaborative note https://hackmd.io/@pghfB_fJTlKAKoeedJTRPQ/rJtbjVExs based on your note and I put the arguments there. Can I invite you to continue to contribute to this notes?

The plan is that I am hoping once we collected sufficient arguments of both side, we turn it into an informative EIP as "EIP Reference Best Practice / Policy"

[kdenhartog]

@SamWilsn @lightclient was just listening to EIPIP call on this topic. Based on the definition in RFC 2119 which is pretty clear about SHOULD NOT it states:

This phrase, or the phrase "NOT RECOMMENDED" mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.

My argument for this would be that linking to normative specifications is a "valid reason in [this] particular circumstance when the particular behavior is acceptable or even useful" because it allows us to be able to directly reference another specification that normatively defines a specific definition or feature so that it doesn't have to be redefined. In the case of W3C here's how they define what can be normatively linked here: https://www.w3.org/2013/09/normative-references

I'd like to make the argument that normative references (e.g. references that directly impact usage of RFC 2119 and meet the quality defined by W3C) meet the exception case where external links are valid and should be allowed assuming it meets the guidelines defined by W3C. This is so EIP editors don't have to define these themselves. This process has worked quite well for W3C so no point redoing what's already been done IMO.

If the case for this is that it should never be done than I believe EIP-1 needs to be updated to MUST NOT which more explicitly aligns with the expectations it sounds like the EIP editors have set.

cc @MicahZoltu as well since it sounds like from #4335 that you've had strong opinions on this as well.

[Pandapip1]

The W3C normative reference document does look like a good starting point. In the meantime, though, the "careful consideration" for the SHOULD requires editor consensus, which is Very Unlikely™ for any given EIP.

[gcolvin]

I've also suggested the IETF style guide. it's much briefer and simpler. I forget where I discussed this,

[kdenhartog]

@gcolvin do you have a link to it? I actually think the direction EIPs are heading is more aligned with IETF's style of thinking so I'd think (without reading it yet) that this could also be a good approach here too.

This is certainly not something that's going to be solved in a day or even likely a month, but I do think it's something that's worth trying to find alignment on for the medium to long term.

[gcolvin]

IETF was the original model. We’ve been discussing this for a while in couple of channels and on one or more PRs, so my comments are scattered. But mainly look at https://www.rfc-editor.org/rfc/rfc7322.html

On Sep 15, 2022, at 5:34 PM, Kyle Den Hartog @.***> wrote:

@gcolvin https://github.com/gcolvin do you have a link to it? I actually think the direction EIPs are heading is more aligned with IETF's style of thinking so I'd think (without reading it yet) that this could also be a good approach here too.

This is certainly not something that's going to be solved in a day or even likely a month, but I do think it's something that's worth trying to find alignment on for the medium to long term.

— Reply to this email directly, view it on GitHub https://github.com/ethereum/EIPs/issues/5597#issuecomment-1248655844, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEAMF6MGZXHWGOJ7CT3NK6TV6OI55ANCNFSM6AAAAAAQFF5JUA. You are receiving this because you were mentioned.

[kdenhartog]

Yeah makes sense, this is one of those topics that I doubt there's a "perfect" solution for, but one where it's circumstantial and dependent on the use case. Main reason I'm bringing it up now is because I'm looking to directly align provider objects with the window.isSecureContext object so in this case directly referencing the W3C recommendation makes sense here.

To me that seems like a good reason to allow referencing, but it seems like there's traditionally been a pretty clear line to not allow them at all in which case I think EIP-1 should change it's text to accurately reflect that sentiment (with MUST NOT) or some general guidelines should be set and built on based on circumstances in the future.

For me, I'm +1 to RFC7322 style guide or W3C normative references, but I think the RFC7322 approach is more comprehensive to address a larger number of process related concerns.

[gcolvin]

I think thatthe ban on references is fairly recent. Certainly some of the earlier ones were full of them. I suppose one could crawl though the commit history of EIP-1 to see when that changed.

On Sep 15, 2022, at 7:30 PM, Kyle Den Hartog @.***> wrote:

Yeah makes sense, this is one of those topics that I doubt there's a "perfect" solution for, but one where it's circumstantial and dependent on the use case. Main reason I'm bringing it up now is because I'm looking to directly align provider objects with the window.isSecureContext object so in this case directly referencing the W3C recommendation makes sense here.

To me that seems like a good reason to allow referencing, but it seems like there's traditionally been a pretty clear line to not allow them at all in which case I think EIP-1 should change it's text to accurately reflect that sentiment (with MUST NOT) or some general guidelines should be set and built on based on circumstances in the future.

For me, I'm +1 to RFC7322 style guide or W3C normative references, but I think the RFC7322 approach is more comprehensive to address a larger number of process related concerns.

— Reply to this email directly, view it on GitHub https://github.com/ethereum/EIPs/issues/5597#issuecomment-1248753443, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEAMF6M3GQQR7AZ2EN4IYS3V6OWQHANCNFSM6AAAAAAQFF5JUA. You are receiving this because you were mentioned.

[gcolvin]

Found a long discussion here: https://hackmd.io/@pghfB_fJTlKAKoeedJTRPQ/rJtbjVExs

[xinbenlv]

Found a long discussion here: https://hackmd.io/@pghfB_fJTlKAKoeedJTRPQ/rJtbjVExs

Thank you! Please feel free to edit that discussion note too @kdenhartog @gcolvin

[kdenhartog]

added a few new points in here @xinbenlv

Something I just realized that's a bit of a hinderance on sticking PDFs in the assets folder like @Pandapip1 suggested is that github doesn't allow linking to specific sections within the document as far as I can tell. This can become an issue when trying to specific reference a normative definition such as https://www.w3.org/TR/secure-contexts/#potentially-trustworthy-origin

[Pandapip1]

Huh, that is an issue. Perhaps we could use https://github.com/mozilla/readability and https://github.com/mixmark-io/turndown to generate markdown files from articles?

[kdenhartog]

I doubt that would work as the assets file would then contain links as W3C documents allow links. If /assets can allow links then this can just be bypassed by referencing a spot within the assets folder and then referencing externally from assets.

E.g. if I wanted to just bypass walidator I could just produce a bibliography PDF which contains the external links and then cite the bibliography as a method to link to external resources.

[Pandapip1]

EIPW doesn't validate files in /assets. Although external links aren't allowed, I would be okay with bypassing this for other specs.

[kdenhartog]

That doesn't seem to be a very consistent application of this rule. This conversation is leaving me more confused about the purpose here of this rule.

[Pandapip1]

So, the rule is that external links aren't allowed. Full stop. Not even in asset files.

However, I would be open to changing that under certain circumstances.

[gcolvin]

I've expressed my strong opinions. I don't think we have consensus.

Per the HackMD linked above, my recommendation: https://hackmd.io/@pghfB_fJTlKAKoeedJTRPQ/rJtbjVExs#Proposed-solution-4-by-gcolvin

[xinbenlv]

Thanks @gcolvin . I understand that we don't yet have a consensus. I intend to facilitate the discussion and hopefully generating a consensus.

[lightclient]

The current policy is that all external links are prohibited.

My policy until eipw was that "high quality" external links were acceptable in ERCs. Now it's not possible without overriding the bot to allow this. But there is no hard rule in EIP-1 to ban external links. My preference is to add support in eipw to allow for links from certain high quality sources like RFC, IETF, consensus specs, etc. Things we have a good expectation of being around in 20+ years.

[MicahZoltu]

I put the odds of the consensus specs being in the same place they are now in 20 years at close to 0%.

[Pandapip1]

Okay, I'll change this:

My rule is that external links aren't allowed. Full stop. Not even in asset files. I generally don't approve PRs that use them and require them to delete those links in order for me to approve them.

So here's the actual policy: different editors have different interpretations. I am generally the most active editor, alongside @SamWilsn. If you want your EIP merged quickly, no external links. If you want to wait for a different editor to approve it, go ahead. Bear in mind that me, @SamWilsn, and @axic are the only ERC editors, and @axic isn't terribly active.

[xinbenlv]

@Pandapip1 I am deeply concerned by this approach that enforce a unilataral preference of personal views instead of the consensus of editors. When acting as editor, one is exercising on behalf of a community and IMHO shall act upon consensus rather than personal view.

[Pandapip1]

"Should" is to be interpreted as exactly what I stated above: each editor has their own views and enforces those views.

I agree that this current phrasing should be somewhat concerning, and that is why we need something better than the word "should."