Alert Source Discuss
⚠️ Draft Meta

EIP-7577: Versioning Scheme for EIPs

Use a versioning scheme for EIPs based on changes made to their Specification section.

Authors danceratopz (@danceratopz), Ahmad Bitar (@smartprogrammer93)
Created 2023-12-13
Discussion Link https://ethereum-magicians.org/t/add-eip-versioning-scheme-for-eips/17295

Table of Contents

Abstract

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.

Motivation

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.

Specification

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:

  1. MAJOR: A breaking change to the specifications that requires an implementation change and a change to the reference tests.
  2. MINOR: An addition to the specifications that requires additional implementation and additional test coverage to be added to the reference tests.
  3. 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:

  1. A new version number that follows the semantic versioning scheme outlined above.
  2. The date when the changes where introduced.
  3. The ethereum/EIPs PR number that implements the changes.
  4. A line for each change made to the EIP’s specifications that includes a short description of the change.

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. Update the EIP version in the metadata header of the EIP’s markdown file. If the EIP’s status is changed from “Draft” to “Review”, the version MUST be updated to 1.0.0.
  2. Add a new CHANGELOG entry based on the EIP Version and the PR’s title.

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.

Rationale

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.

Case Study

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.

Changelog

  • 9.0.1 - 2023-09-26: Update ring buffer size rationale for new ring buffer size, #7786.
  • 9.0.0 - 2023-09-26: Post audit tweaks, #7672.
    • Verify timestamp is non-zero.
    • Make HISTORY_BUFFER_LENGTH prime (8191).
    • Load calldata once.
    • Update BEACON_ROOTS_ADDRESS.
  • 8.0.1 - 2023-08-28: 4788 cleanups, #7532.
  • 8.0.0 - 2023-08-24: Initial stab at v2, #7456.
    • Require timestamp input to be exactly 32 bytes.
    • Revert if timestamp input does not match stored value (instead of returning zeroed word).
    • Remove precompile concept, use regular smart contract with provided bytecode.
  • 7.0.3 - 2023-08-01: Mention genesis block with no existing beacon block root case, #7445.
  • 7.0.2 - 2023-07-07: Explicitly specify header schema, #7297.
  • 7.0.1 - 2023-07-07: Fix typo, #7293.
  • 7.0.0 - 2023-07-05: Bound precompile storage, #7178.
  • 6.0.1 - 2023-06-13: Clarify header and validity sections, #7179.
  • 6.0.0 - 2023-06-12: Update precompile address, #7173.
  • 5.0.0 - 2023-05-31: Key beacon roots by root, #7107.
  • 4.0.0 - 2023-05-24: Favor stateful precompile over opcode, #7065.
  • 3.0.0 - 2023-05-17: Send current slot from CL to avoid timestamp conversions, #7037.
  • 2.0.1 - 2023-05-15: Fix typo, #7005.
  • 2.0.0 - 2023-05-03: Update opcode to avoid clash, #6980.
  • 1.0.1 - 2023-04-13: Minor nits, #6870.
  • 1.0.0 - 2023-04-11: Use block roots; update to status “Draft”, #6859.
    • Update to “Draft” due to client implementation (NethermindEth/nethermind#5476).
    • Use block roots instead of state roots.
    • Roots are stored keyed by slot.
    • Use of ring buffer in state.
    • Use header timestamps to derive slot numbers, rather than consume additional header space.
  • 0.2.1 - 2023-02-04: Update to status “Stagnant”, #6432.
  • 0.2.0 - 2022-06-29: Rename “beacon block root” to “beacon state root”, #5090.
  • 0.1.1 - 2022-05-06: Force usage of included LICENSE file, #5055.
  • 0.1.0 - 2022-02-17: Add EIP-4788: Beacon state root in EVM, #4788.

Backwards Compatibility

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.

Security Considerations

None.

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

danceratopz (@danceratopz), Ahmad Bitar (@smartprogrammer93), "EIP-7577: Versioning Scheme for EIPs [DRAFT]," Ethereum Improvement Proposals, no. 7577, December 2023. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-7577.