This EIP suggests a semantic versioning scheme for Standard Track EIPs based on their Specifications section to help remove ambiguity when discussing changes and tracking implementations.
An extended rationale that demonstrates how this can be used within the EVM Testing Toolchain can be found here.
@danceratopz & Ahmad Bitar thanks for sharing about this proposal in EIPIP Meeting 96.
This obviously will help in testing Standard Track - Core proposals. However, I can imagine a few other use cases of this proposal across EIP types/categories.
The EIP versioning scheme MUST follow a semantic versioning scheme of
MAJOR.MINOR.PATCH, which is applied as follows:
MAJOR: A breaking change to the specifications that requires an implementation change and a change to the reference tests.MINOR: An addition to the specifications that does not require changing an existing implementation, but requires additional implementation and additional test coverage to be added to the reference tests.PATCH: Any cosmetic change to, or a reformulation of, the EIP without specification change.
In my mind, with slight changes, we can perhaps increase use cases. Instead of MAJOR.MINOR.PATCH may we consider STATUS.SPECS.PATCH (x.y.z)?
Acceptable values (for x)
LivingDraftReviewLast CallFinalStanantWithdrawnAcceptable values (for y)
Change of value to default
Acceptable values (for z)
Change of value to default
I wonder what are the thoughts on
EIP-Preamble: This will help read the proposal status by just checking the version. It can be checked and automatically/manually allocated to a proposal by an EIP editor and be super helpful for toolings around EIPs.Final EIPs among other changes.Recommendation on the default value for retroactive implementations will be STATUS.0.0
eg. For proposals in Final status, the Version = 4.0.0.
Advancing EIP-7577 using the versioning feature as described can be a good example. However, I understand it may not be doable instantaneously without updating bots.
In the current architecture of the EIP repository, once an EIP reaches a “final” status there is no way to modify it, not even if a security consideration is found.
My suggestion: add a mechanism that is available in the IETF’s RFC repository: an “Updated-by” or “Replaced-by” tag.
This way, a reader of an EIP can clearly see there is further discussion after the current ERC was finalized.
Updated-by should be marked even if the updating EIP is in “draft” (its an “FYI” notice)
Replaced-by should only be marked once the referencing EIP is finalized, and thus the current one becomes completely obsolete.
(both tags are added to existing EIPs once a new document with “Updates” or “Replaces” header tags, respectively, is added to the repository)
Thanks @dror for adding feedback.
It is correct that the Final EIP represents the final standard and is not open to accept modification.
However, there is a small room for non-normative changes. As per EIP-1
“A Final EIP exists in a state of finality and should only be updated to correct errata and add non-normative clarifications.”
So, if there is a general agreement of moving forward with the version scheme for EIPs, perhaps Final EIPs can also be updated to 4.0.1 where
FinalIf not, then moving EIP versioning ahead with non-Final EIPs should be okay as well.
I am aware of the interest in discussing the process for updating Final Ethereum Standards under exceptional circumstances like security considerations. It was mentioned in the last meeting and is in active discussion in EIPIP meetings and we hope to get to talk about specific conditions under which Final EIPs can be updated. We encourage people to join the meeting or leave comments to participate in discussing edits to Final standards.
Just to be clear that this is more or less exactly the proposal in a parallel discussion, motivated especially by finding new security considerations.
The idea that a standard will be final is really appealing, but seems to push hard against reality. My 25-odd years working with W3C suggest that the goal of making a final complete standard (as opposed to the next version of something that needs to be tweaked at least from time to time) causes a lot of problems.
Over time it gets harder to fix things (update to EIP-1 anyone?) but they can still be fixed - or get completely replaced by something people believe will be easier to manage into the future. So I would like to see this discussion continue, until it reaches the point where we have a working visible concept of “this EIP is obsolete, go look at that one that replaces it”, without simply allowing anyone to claim their new thing obsoletes what the world is using.
I’m not a fan of “living” as a status - that is the status of anything that is still used.
I have an approach that is a bit like @poojaranjan backwards: Version, then status (I have “draft” and “done”). I think it’s critical to have a mechanism for a specific spec (or version) to point forward to its replacement, and this is not hard. I’m not that keen on patching old versions - if they are hanging around long enough that it is really important, then it means the next version didn’t reach the status people thought, and some more work needs to be done on re-doing the transition.
But I think people in this community understand “semantic versioning” and are used to it. It’s probably more useful to question whether we’re prepared to accept that “Final” is not real and that we should version things or not, and expect that the answer if we do versioning will be that.
Philosophically, it comes down to are you optimising for stability or innovation? In particular what is the meaning of a standard?
technical discussions (technical control along bottome) in the rough consensus, working code stage need more precise versioning so details can be thrashed and matters that have been settled, can pinhole cite in case later participants raise variations of the same objective.
on the other hand businesses that are looking to invest significant resources into an DLT, would like to see certainty in the timescale of decades (middle left)… which means distrust of anything too new so finality is welcome … even with known bugs (cough browser feature sets), they can be worked around because cross-chain consistency is more important.
the gap between where new knowledge (eg of vulnerabilities) arises and the standards are slow to update are where attacks have the biggest detrimental impact. You can have different “standards” (eg tech and legal) moving at different speeds, so long as there is a clear coupling / stapling between the two. For example, the tech standard might say every 5-7 years have a review which then gets compiled in the market accepted practices which can be ratified at the legislative/regulative level (middle right of centre).
However, there should be some way of clustering closely related topics … at the moment, variations of treating NFTs are numbers across quite unrelated pull requests. An complementary proposal would be
For easy human memonics, EIPeditors should have the discretionary power to alias ERC-??? [alpha] to a future EIP …
eg ERC-20A might be aliased to that EIP which calls a recipient function upon transfer if commonly used). That way you’d only need to recall the shortened form.
Hi @poojaranjan, many thanks for your input! And please excuse my delayed response!
Ahmad and I discussed this and while we understand the motivation behind this suggestion, we’d prefer to maintain a pure semantic versioning scheme (semver). For the main part, developers and authors should be familiar with semver and will hopefully intuitively understand how it should be applied.
Using STATUS in STATUS.SPECS.PATCH (x.y.z) will duplicate information. Additionally, one disadvantage of this approach is that versions will not strictly monotonically increase, as an EIP’s STATUS can move from, for example, DRAFT → STAGNANT → DRAFT.
Here’s a comment on the usefulness of each field: Assuming we use MAJOR.MINOR.PATCH. We expect that the vast majority of changes will be either:
MAJOR “A breaking change to the specification…”, or,PATCH “Any cosmetic change to, or a reformulation of, the EIP without specification change.”.We expect that the MINOR field “An addition to the specifications that requires additional implementation….” will not see heavy use, as this kind of change appears to be rarely made to EIPs (see, the EIP-4788 Case Study here or in the PR). We feel, however, that the intention of bumping the MINOR version matches semver well in the context of specification changes. But we are open to other suggestions!
Yes, this should be added to an EIP’s metadata. This has been added to the proposal (see 92fb8ba7#L43).
We don’t feel that retroactively applying versioning to EIPs is necessary or particularly valuable, as the main value of versioning is during the development phase. I don’t think it’d be possible to automate this process reliably. We could allow EIP authors to apply it retrospectively their EIPs if they wish.
Thanks @dror for this comment and @chaals for linking the discussion and further comments on how to deal with obsolete EIPS, specifically EIPs that have been superseded by a subsequent EIP.
As per @poojaranjan’s comment above (as per EIP-1, non-normative changes are allowed), 7577 would allow for a transparent history of errata made to EIPs.
I see the value in an “Updated-by” tag (or new metadata field?). I’m not sure if it should be scoped in 7577, as this EIP is concerned with helping to improve the current development process of active EIPs, respectively, maintaining a transparent history of changes to EIPs (including errata). I hope the discussion around this continues! If the community agrees and it fits in within the scope of 7577 we can consider to include it later. However, I feel this would deserve its own separate proposal.
Thank you for your proposal @danceratopz
On a high level I like supporting versioning of EIPs.
Some brief thought:
0. Currently any EIP author can add versions in their draft already by adding to their EIP text body. We just need to advocate for @danceratopz 's proposal to be adopted as as drafting practice.
Meta EIP updating preamble.I would be supportive of adding version to preemble if-and-only-if we see many authors using EIP versioning within their own EIP drafts already.
I like this idea overall, with some caveats:
Changelog section as optional and basically having every MUST in your spec be a MAY.updated-on header field that is changed to the current date every time the EIP bot merges a PR. This means that unless we get many changes in a single day, we’d easily be able to differentiate between two versions of an EIP.With these two changes, people can always know if/when an EIP was updated and authors are nudged to track changes, but EIPs aren’t stuck with open PRs for longer than they currently are. Avoiding PRs being open for a long time seems like the most critical thing, as the “true spec” isn’t even reflected in the EIP.
Thanks for the comments @xinbenlv!
Would you suggest the version gets added to a “Changelog” section?
Whilst it would be possible, albeit a bit clunky, for external tooling to parse the version from an ordered Changelog section, it could get messy (and be more of a burden to EIP authors) without adding the suggested automated tooling (i.e., allow bumping of the version based on commit message, cf 45587bd0/EIPs/eip-7577.md#L43-L50).
As I understand, it would also require EIP-7577’s status to be bumped from Draft to Review, so that the EIP using 7577 versioning could add EIP-7577 to it’s requires header preamble?
Thanks a lot for checking out the proposal, @timbeiko!
First, as versioning is not required before Review status, authors can iterate freely without considering versioning whilst the EIP has Draft status (versioning adds value when multiple teams are involved and implementation starts).
Secondly, also with regards to bikeshedding, assessing the impact of a PR made to an EIP should be a relatively simple task in the majority of cases (i.e., spec change: bump major version, improve rationale: bump patch). Additionally, the version bumping and Changelog line should be largely automated (the version gets bumped based on one of the PR’s commit messages and the changelog line could come from the PR’s title, see 45587bd0/EIPs/eip-7577.md#L43-L50).
This needs further discussion though! Also with client teams as maintaining a list of EIPs and their implemented versions will cause additional effort for them.
Whilst an updated-on header field could help resolve ambiguities across software components and discussions, without expressing the change richly as a semver, we won’t be able to automatically evaluate changes within the testing framework when testing client implementations (for example, in order to apply “xfails” or issue warnings, cf 45587bd0/EIPs/eip-7577.md#L56). The idea of comparing client implementation, test implementation and spec versions is also explained in more depth in Example 3: EVM Testing Toolchain in the extended rationale.
I suspect that if EIP versioning consisted of an updated-on preamble field as a timestamp it would not receive adoption in client implementations and test frameworks. Issuing a warning in test frameworks upon any change to an EIP would be too noisy for it to be useful.
Additionally, I think it’s simpler to compare versions (rather than a timestamp) in an ACD discussion or a devnet spec page 
.
I agree with you that this seems simple in theory! That said, after spending good part of my morning trying to move a bunch of EIPs from Draft to Review, and being blocked on about half of them for various reasons (context), I’ll reemphasize that any extra mandatory checks on EIPs probably is a net negative in terms of productivity given the extra friction. My suggestion would be to try and run the process in a 100% optional way at first, see it working, and then determine what you want to make mandatory and how 
I think your concerns with updated-on are valid. IDK if there’s another type of status you could auto-generate based on EIP updates?