Skip to content
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.

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

Create a plan for better versioning of remote-apis #315

Open
bergsieker opened this issue Oct 9, 2024 · 1 comment
Open

Create a plan for better versioning of remote-apis #315

bergsieker opened this issue Oct 9, 2024 · 1 comment

Comments

@bergsieker
Copy link
Collaborator

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.
@bergsieker
Copy link
Collaborator Author

After thinking about this further, I think that we should keep SemVer for the APIs, but switch to date-based versioning for the github releases. Doing so will alleviate a lot of confusion about how to the two layers interact.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant