EIP-5757 External resource approval process (Process for Approving External Resources)

Final · Other · EIP status Final · created 2022-09-30

Defines the three requirements an origin must meet to be linked when an EIP references external resources outside the repository, along with the process for approving and removing origins.

Why it is needed

EIPs sometimes link to external resources outside the repository, such as documents from other standards bodies, books, or papers. However, the EIP repository has no control over external resources. If there is no way to pin down a specific version of a resource, changes to its content become hard to track, and the evidence a standard points to can effectively shift. Also, if a resource is essential to implementing a standard, implementers must be able to access it at any time; if the source disappears or goes behind a paywall, the standard becomes hard to implement. The Ethereum ecosystem is built on openness and free access, so the EIP process must follow the same principles. To prevent this problem, this EIP defines three requirements that a linkable source, or origin, must meet, and a process for approving and removing origins.

What changes

Today

After EIP-5757

Who is affected

In depth

Three term definitions

The original text defines three terms. A Link is any way of pointing to another resource, including Markdown links, anchor tags (<a>), images, and citations in books or journals, essentially any method of referencing content not present in the current material. A Resource is a medium containing content, such as a web page, document, article, file, or book. An Origin is the entity that publishes or records a resource; the original text gives standards bodies like the W3C and document reference systems like the Digital Object Identifier System (DOI) as examples. Requirement-level terms such as MUST and SHOULD follow the interpretation in RFC 2119.

Three requirements an origin must meet

An allowed origin must satisfy three requirements. First, it MUST provide a way to uniquely identify a specific revision of the resource; examples given are a git commit hash, a version number, or a publication date. Second, it MUST have a proven track record of availability; the original text notes that an origin existing for 10 or more years with a reliable record of serving the resource is sufficient to meet this requirement, though not strictly necessary. Third, it MUST NOT charge a fee for access to the resource.

Rules for origin removal

If an approved origin no longer meets the above requirements, it MUST be removed from EIP-1. A removed origin that later meets the requirements again MAY be re-approved by going through the approval process again. How existing links are handled depends on the EIP's status. Finalized EIPs, such as those in Final or Withdrawn status, SHOULD NOT be edited to remove links to that origin. Non-finalized EIPs MUST remove such links before changing status.

Origin approval process

When an editor determines that an origin meets the requirements, EIP-1 MUST be updated. The update includes three things: the name of the approved origin, the markup allowed and formatting required when referencing that origin's resources, and a fully rendered example of how the link should appear. Approval is not just adding a name to a list; it also standardizes how links to that origin are written.

Rationale for the three requirements

Unique identifier: without a way to uniquely identify a version of a resource, tracking changes becomes impractical and immutability cannot be guaranteed. Availability: if a standard can be implemented without the linked resource, the resource is unnecessary; if it cannot be implemented without it, implementers must be able to access it. Free access: the Ethereum ecosystem is built on openness and free access, and the EIP process must follow the same principle.

Document nature and status

This EIP is a Meta type, dealing with the EIP process itself rather than protocol code, and its status is Final. This means its content is finalized and the rules apply to the current EIP editing process. It references EIP-1 with a requires dependency, and the list of approved origins and link formats are recorded and updated in EIP-1, not in this document. Copyright has been waived under CC0.

Original EIP · ← EIPs