bazelbuild / bazelbuild/remote-apis

Create a plan for better versioning of remote-apis

Open
#315 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
445
Forks
141
PR merge metrics
No merged PRs in 30d

Description

tl,dr: We plan to start monthly releases from the remote-apis repository. The releases will follow SemVer semantics for the Execution API.

We've generally been pretty lax about creating proper releases from this repository. This isn't ideal for a number of reasons, but the most pressing one right now is that it doesn't work well with bzlmod--registering remote-apis in BCR requires an actual version number.

Proper versioning is complicated by the fact that there are actually multiple "versions" in play here: the repository contains three different APIs (execution, asset, and logstream), and the release version is technically orthogonal to the underlying API versions. So, a pedantic solution would require documenting the precise version number in the proto files for each API, then creating releases with a standalone numbering scheme--so github release v1.0.0 might contain execution v2.12.0, asset v1.1.0, and logstream v1.2.0. Yuck.

All that said, the current "lazy" scheme has honestly been working reasonably well, and I don't see a really sound reason to take on the extra work of full release engineering at this time. Ed proposed simply moving to a monthly release cadence, which seems like a good way to start getting more regular releases without taking on a bunch of extra work. I propose this plan:

1) We will cut a release around the time of each monthly meeting. We can use the first part of the meeting to discuss the release.
2) Just as now, we will have one Github release that includes all three APIs, in both proto and generated-code form.
3) If there are no changes in a given month, there will be no release.
4) We will continue to use SemVer semantics for releases. Specifically, backwards-compatible new functionality will trigger a minor release bump. Smaller changes and bugfixes (e.g., in the generated code bindings) will trigger a point release.
5) For our purposes, clarifications to comments in the APIs are considered a "small change" and will trigger a point release. This is a little strange--such changes technically don't change the API at all--but I think it's useful to include them in an actual release artifact.
6) Github release numbers will follow the versioning of the execution API. However, we also need to find a way to incorporate changes to the asset and logstream APIs if there are changes to those APIs but not the execution API. Such a release will trigger a point release bump for the Github release, and this will create an implied point release bump for the execution API. That's a little annoying--we'll be creating unnecessary point release versions for the execution API--but seems like the easiest way to handle this.

Contributor guide

Open the contributing guide

Research direction

Start with the six-point proposal in this issue and review the repository's current GitHub release process and BCR registration requirements. Done means an agreed, documented versioning plan covering monthly releases, SemVer behavior, and changes to all three APIs; no files or tests are named here.

Written by the indexing model from the issue text.

Assessment

Tech stack
github
Domain
build-system, release
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.