Skip to content

Update README with versioning information #704

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update README with versioning information #704

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 36 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,15 +37,15 @@ will have all schema `#ref`s resolved.
#### Building the docs

Once you've updated something in the spec, you can use the docs generation tools
to view the updated specs locally.
to view the updated specs locally.

```console
$ npm run build:docs
$ npm run watch
```

The `watch` command starts a local webserver serving the docs in-browser at
`http://0.0.0.0:8000` and it rebuilds when you update something in the specs.
The `watch` command starts a local webserver serving the docs in-browser at
`http://0.0.0.0:8000` and it rebuilds when you update something in the specs.
Please reload the page to see your changes.

### Testing
Expand All @@ -69,7 +69,7 @@ directory against the specification. There are two npm scripts to simplify this

```console
$ npm run build:test
$ npm run test
$ npm run test
all passing.
```

Expand Down Expand Up @@ -129,6 +129,37 @@ A script is included in the source code which reads and validates the given sche
$ npm run graphql:validate
```

## Versioning

Execution-apis follows [semantic versioning][semver].
- Major releases will include breaking changes to the [rpc-compat hive tests][rpc-compat], and other backwards incompatible changes.
- Minor releases will include new backwards-compatible features.
- Patch releases will include internal changes that don't impact end users and backwards-compatible bugfixes, along with fixing test cases that don't match the spec.

Examples of changes by version type:

**Major:**
- Adding new RPC methods
Copy link
Member

@danceratopz danceratopz Nov 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Adding new RPC methods
- Removing an existing RPC method

Copy link
Contributor

@macfarla macfarla Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you could clarify it by saying "Adding tests for a new RPC method"

- Changing the parameters or return type of an existing method in an incompatible way
- Renaming fields in responses
- Changing error codes or error response structures
- Removing support for previously accepted input formats
- Adding new fields to response objects

**Minor:**
- Removing an existing RPC method
Copy link
Member

@danceratopz danceratopz Nov 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Removing an existing RPC method
- Adding a new RPC method

Copy link
Contributor

@smartprogrammer93 smartprogrammer93 Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think both adding and removing should be in major. Here we are talking about what breaks hive tests not what breaks user experience. As such, both adding and removing is a major break in hive

Copy link
Collaborator Author

@kclowes kclowes Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, exactly. As I'm optimizing for client developer experience here, adding a new RPC method will start clients failing on hive and so I think it should be a major. I can see either way on removing, but had it in minor because it won't change whether or not clients pass the hive tests.

Copy link
Contributor

@macfarla macfarla Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you could clarify it by saying "Removing tests for an existing RPC method"

- Adding optional parameters to existing methods
- Adding new error codes for previously uncovered edge cases
- Introducing new capabilities while maintaining backward compatibility

**Patch:**
- Fixing typos or improving clarity in documentation
- Correcting examples in the specification
- Fixing test cases that don't match the spec
Copy link
Contributor

@macfarla macfarla Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this one maybe should be minor? if clients are matching the tests rather than the spec (which is not uncommon), this will break things

- Improving validation rules without changing the API surface
- Updating internal tooling or build processes


## License

This repository is licensed under [CC0](LICENSE).
Expand All @@ -144,3 +175,4 @@ This repository is licensed under [CC0](LICENSE).
[hive]: https://github.com/ethereum/hive
[rpc-compat]: https://github.com/ethereum/hive/tree/master/simulators/ethereum/rpc-compat
[test-gen]: docs/reference/tests.md
[semver]: https://semver.org/
Loading