Add EIP: Versioning Scheme for EIPs #8034
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,110 @@ | ||||||
| --- | ||||||
| eip: 7577 | ||||||
| title: Versioning Scheme for EIPs | ||||||
| description: Use a versioning scheme for EIPs based on changes made to their Specification section. | ||||||
| author: danceratopz (@danceratopz), Ahmad Bitar (@smartprogrammer93) | ||||||
| discussions-to: https://ethereum-magicians.org/t/add-eip-versioning-scheme-for-eips/17295 | ||||||
| status: Draft | ||||||
| type: Meta | ||||||
| created: 2023-12-13 | ||||||
| --- | ||||||
|
|
||||||
| ## Abstract | ||||||
|
|
||||||
| This EIP introduces a versioning scheme for [Standards Track](./eip-1.md#eip-types) EIPs by applying [Semantic Versioning 2.0.0](../assets/eip-7577/semver.md) based on changes made to the EIP's Specification section once its status has changed from `Draft` to `Review`. | ||||||
|
There was a problem hiding this comment.
Suggested change
To my best understanding this proposal is about versioning within EIP instead of across EIPs, right? |
||||||
|
|
||||||
| ## 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 | ||||||
|
|
||||||
danceratopz marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| 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](../assets/eip-7577/semver.md): | ||||||
|
|
||||||
| 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. | ||||||
|
There was a problem hiding this comment.
This should have higher billing. Like the first line after the RFCs. As well as the new changelog section. Also, we should update the EIP template to add these two new feaures as part of this EIP when it goes final. |
||||||
|
|
||||||
| 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](./eip-4788.md) 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 | ||||||
|
|
||||||
| Copyright and related rights waived via [CC0](../LICENSE.md). | ||||||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wonder if this shall be
InformationalorMeta. I like the idea and direction. I don't think every EIP needs adopt it