This EIP introduces a versioning scheme for Standards Track EIPs by applying Semantic Versioning 2.0.0 based on changes made to the EIP's Specification section once its status has changed from Draft to Review.
EIP specifications often receive increasing modifications as more people review them, which is generally the case as client teams start implementing the specifications and the community gains a better understanding of their interaction with the rest of the protocol. These changes can be difficult to track. In particular, as EVM reference tests are often not maintained (and generally not released) by client teams or the EIP's authors, it can be difficult to ascertain whether a release of reference tests is sufficient, or even valid, to test the latest version of an EIP's specifications or the specification as currently implemented by a client.
This EIP proposes a semantic versioning scheme and an addition of a CHANGELOG section for EIPs that enables clearer communication within the community and allows the scope of a change to be ascertained at first glance. Furthermore, client implementation and testing toolchains can query EIP changes and automatically flag incompatibilities between the EIP's current specification and between client and test implementations.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
Once an EIP has moved out of "Draft" status, it MUST use the EIP versioning scheme outlined below. It MAY already use the versioning scheme in "Draft" status, which could be useful if the specification is actively being implemented. If more than one team is implementing the specification, it is RECOMMENDED to change the EIP's status to "Review".
The EIP versioning scheme MUST apply the following semantic versioning scheme of MAJOR.MINOR.PATCH, based on Semantic Versioning 2.0.0:
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 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.Before the EIP has moved out of Draft status and is being versioned, the version number MUST initially have MAJOR version 0.
For every change made to an EIP via a pull request (PR) made to ethereum/EIPs, a new entry MUST be added to the CHANGELOG section of the EIP that outlines the changes made within the PR. This CHANGELOG entry MUST include the following:
Additionally, the new version MUST be added to the metadata header of the EIP's markdown file (to a new "version" field), so that it may be easily parsed.
Tooling MUST be added to the ethereum/EIPs repository to help EIP authors apply the versioning scheme. This tooling SHOULD automatically:
1.0.0.To allow the tooling to make these changes, the EIP author MUST indicate the scope of change in one of the commit messages pushed to the PR's branch. The scope is indicated by starting a commit message with ("[Mm]ajor:", "[Mm]inor:", or "[Pp]atch"). Multiple commit messages may contain scopes; in this case, the most severe scope change will be applied. If no scope can be detected in any of the commit messages, merging of the PR is blocked until such a commit message is pushed to the PR.
Making the version available in the EIP's metadata header allows for programmatic parsing of the version number by tooling used in reference tests or by client teams. Currently, the execution-spec-tests repository, which contains consensus tests for Ethereum execution clients, implements a rudimentary EIP version checker: EIP spec tests are required to declare the EIP's markdown file digest SHA that the test implementation was based on. The current value of the digest SHA is then polled via the Github API to verify that no changes have occurred since the test implementation. While this provides a warning to test implementers that the EIP has changed, it is clearly of limited use.
A richer versioning scheme, as defined by this EIP, can provide a lot of value to the testing toolchain. Client teams can provide an interface that reports the EIP version currently implemented and reference tests can specify the version they implement in generated tests as metadata. This allows a test runner to mark tests to xfail (expectedly fail) and issue a warning if the MAJOR or MINOR versions don't match. It would even be possible to automatically select the correct version of the reference tests to run against a client implementation, although given the pace of Ethereum development, it will likely be impractical to maintain and track multiple versions of tests.
This section explores how the versioning scheme would be applied to an existing EIPs recently under active development at the time of writing as an example.
The history of EIP-4788 contains many changes to its specification. EIP-4788 was updated to status "Review" on 2023-11-28. This case study assumes, however, that the EIP moved to status "Review" as of 2023-04-11 and updated to version 1.0.0 due to the start of a client team implementation.
HISTORY_BUFFER_LENGTH prime (8191).BEACON_ROOTS_ADDRESS.It is not necessary to retroactively add a CHANGELOG or versions for versions of the EIP prior to the introduction of this EIP. Upon the next change to the EIP's Specification section, the author MUST introduce a CHANGELOG section and a version number that follows the semantic versioning scheme outlined above.
None.
Copyright and related rights waived via CC0.