bazelbuild / bazelbuild/remote-apis
Should we make a resolution to NOT have a v3?
- Dominant language
- Go
- Stars
- 445
- Forks
- 141
- PR merge metrics
- No merged PRs in 30d
Description
It seems like Remote API V2 has been getting a lot more traction since 2018.
Together with it is a wide list of build tools servers and vendors, https://github.com/bazelbuild/remote-apis?tab=readme-ov-file#api-users, adopting the specifications.
Given the recent industry lessons from Golang V2 (or the lack thereof) and Nix Flakes, and the good old Hyrum's Laws;
In combination with how https://github.com/bazelbuild/remote-apis/milestone/1 has been stale/stagnant for a few years now,
I want to put forward a simple question for discussion:
> Should RE API V3 be considered harmful?
In my personal opinion:
- Having a non-backward compatible V3 will create many toils for both clients and servers who have adopted Remote API V3. This burden of migration will not come for free, and will likely trickle down to adopters of these clients and servers implementation.
- Leveraging Protobuf and GetCapabilities RPC, we should be able to continue developing V2 API in a backward-compatible way with a proper deprecation policy. For example, we should be able to work on https://github.com/bazelbuild/remote-apis/issues/99, or https://github.com/bazelbuild/remote-apis/issues/134, and deprecate the field after 5-10 version releases. Clients could rely on the version range provided in the GetCapabilities RPC spec to determine whether the server would support that field or not to make the appropriate adjustments.
- Being able to definitively say that there will be no V3 would allow us to encourage folks to work on more innovative changes to the API spec, instead of pushing them away to some imaginary point in the future. Instead of saying "This might be a good fit for V3", we should push forward new ideas and guide the innovators, through an RFC process, to make their ideas backward compatible as much as possible.
Contributor guide
Research direction
Read the Remote API V2 and V3 discussion, milestone 1, and the linked issues #99 and #134. Compare the proposed backward-compatible evolution through GetCapabilities with the case for a non-backward-compatible V3; done means the project reaches and records a decision on the API versioning policy.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 15/100