Add an optional `relates-to` preamble key
xinbenlv opened this issue · 17 comments
It seems @Pandapip1 has been suggesting using requires: to add EIP that is related. but I think there is a strong need to differentiate "requires" vs "related to" for example, in some of the EIP, they are related and often implementations complied with bot at the same time, but they are decoupled and meant to allow to be implement without one-another, such as #1202 vs #5267.
Hence, I propose to add relates-to as an optional field
Would you mind if I draft a PR? It's usually the way that these changes get made the quickest.
The way I currently interpret required is that the specification requires another EIP in order to be fully read/understood. This would be useful if one wanted to archive a single EIP, you would also need to traverse through every referenced EIP as well and archive them, else the EIP would be incomplete.
I'm not against renaming the field, but I am weakly against (open to discussion) adding a separate second field. I suspect a lot of people read the required field from the context of writing an interface, where their interface has a dependency on some other interface. However, many EIPs don't have that type of dependency and the requires only is meant to indicate that the reader will need to read some other things as well to fully understand the specification or its supplemental data.
To quickly summarize past discussion on this topic, there are two different viewpoints on what the problem actually is:
(1) requires: is a misnomer because the EIPs in the list aren't necessarily required to implement the EIP (for example EIP-4337 mentions EIP-3074 because they are somewhat related, but in no way is EIP-3074 required for EIP-4337 to be implemented.) The solution is to rename requires: to references: or relates-to:.
(2) requires: is not a misnomer, and we need a separate way to prevent final EIPs from linking to non-final EIPs. The solution here would be to either add a separate relates-to: field, or have the EIP validator scan for links in the body.
To quickly summarize past discussion on this topic, there are two different viewpoints on what the problem actually is:
(1)
requires:is a misnomer because the EIPs in the list aren't necessarily required to implement the EIP (for example EIP-4337 mentions EIP-3074 because they are somewhat related, but in no way is EIP-3074 required for EIP-4337 to be implemented.) The solution is to renamerequires:toreferences:orrelates-to:.(2)
requires:is not a misnomer, and we need a separate way to prevent final EIPs from linking to non-final EIPs. The solution here would be to either add a separaterelates-to:field, or have the EIP validator scan for links in the body.
I think that's a good summary. Shall we take it to the EIPIP meeting for an easier discussion?
To quickly summarize past discussion on this topic, there are two different viewpoints on what the problem actually is:
(3) People shouldn't be linking to other EIPs that are not critical to understanding the EIP in question, and if an EIP is critical to understanding the EIP in question then it is "required reading".
To quickly summarize past discussion on this topic, there are two different viewpoints on what the problem actually is:
(3) People shouldn't be linking to other EIPs that are not critical to understanding the EIP in question, and if an EIP is critical to understanding the EIP in question then it is "required reading".
I wonder how many reader and authors refer to 'requires' field when they mean 'require reading'...
Somewhat relevant to this discussion: in ethereum/eipw@d8a40d1, I added a lint that checks links in the body to make sure their status is at least as advanced as the EIP being linted.
I believe that satisfies @MicahZoltu's immutability concern, regardless of what ends up in the requires: header?
Yes, it does if we make EIPW required. required field because it encourages authors to reference as little external stuff (even other EIPs) as possible, and nudges them away from wanting to include a history lesson in their standards.
Many authors have a bunch of material in their motivation/rationale that basically reduces to "I don't like the 15 other standards, so I am writing a 16th standard that is better". Ideally, authors would write a useful standard in isolation and leave that sort of text for a blog post, autobiography, or made-for-TV movie about the life of the author.
One thing I'll add about this is that the main reason to not have external links in the EIPs is because we want to make the EIP editor role as easy as possible and not require judgement about every link in an EIP. IMO this proposal adds this level of overhead to editor's role, and adds way less value than allowing (high quality) external links (e.g. only links to the EL/CL specs). If we do have an "EIP editor judgement/complexity" budget, I'd much rather we spend it on a good policy around external links. Just my 2 gwei :-)
@timbeiko Is your thinking that if we had relates-to and requires both then it means that editors would have make judgement calls whether a given external EIP was a require vs related link?
Unrelated: I like calling it an "EIP Editor Judgement Budge".
Yes, and "relates-to" is pretty vague, so do we just accept anything by default? If so, are there "abuse" vectors, e.g. saying your EIP relates-to EIP-20, EIP-721, EIP-1559 just to make it look more legitimate? requires is more of an objective assessment (and could perhaps be automated if using executable specs!)
There has been no activity on this issue for 1 week. It will be closed after 3 months of inactivity.
Still relevant
There has been no activity on this issue for 1 week. It will be closed after 3 months of inactivity.
There has been no activity on this issue for 1 week. It will be closed after 3 months of inactivity.
This issue was closed due to inactivity. If you are still pursuing it, feel free to reopen it and respond to any feedback.