bazelbuild / bazelbuild/remote-apis

Should we make a resolution to NOT have a v3?

Open
#271 2 comments 1 reaction 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.