API Versioning

[0xemc]

TLDR

I'm starting to lean more towards daily releases (https://calver.org/)

Why

I was writing out some guides for release processes and it became clear that semver (maintaining information about major,minor,patch changes) inevitably requires maintaining multiple versions across time.

The main reason is that we are allowing potentially breaking changes (for consumers) in the form of api improvements to be pushed out in releases and then expecting to do a catch up later (potentially with many changes to absorb)

This in combination with forcing change sets with PRs to be split causes a bunch of headaches.

I see 3 possible scenarios for changes to be made to the API source code:

• Critical Bug In Production
• Changes Required for a Feature
• API Improvement

For comparison these are two possible sets of process:

Semver Process

Critical Bug in Production

1. Create a branch from whatever the current tag targeted by the app is (e.g v2.0.0 -> hotfix/v2.0.0). This will become a long running hotfix branch for that version.
2. Create a second branch from this hotfix with an alphabetical character appended or incremented (e.g hotfix/v2.0.0-a)
3. Create your PR from this new branch targeting the hotfix branch from step 1
4. (If necessary) After the above PR is merged, immediately follow the API Improvements process with the changes in the hotfix.

Changes Required for a Feature

Feature API changes Should ALWAYS be backwards compatible
I havent worked this out yet but it would involve multiple branches and be similar to Critical Bug in Production

API Improvements

1. Create a branch from staging with the version to be released (e.g carbonmark-api/release/vX.X.X)
2. Implement changes and update the carbonmark-api/package.json with the new version.
3. Create PR to staging

Calver Process

Critical Bug in Production

1. Create a branch from staging
2. Implement changes across both /carbonmark-api & /carbonmark
3. Increment carbonmark-api/.package.json & target version in constants.ts
4. Create PR

Changes Required for a Feature

Same as Critical Bug in Production ^

API Improvements

Same as Critical Bug in Production ^

Essentially we have flipped the effort burden to be from fixing bugs and developing features (which are our most common processes) on to API Improvements which are the least common process.

The key to this process requires that API and App changes (the combined changeset) can be reviewed and delivered simultaneously.

[Atmosfearful]

I'm still not seeing the light...

I see dates as having their own tradeoffs, some are very nice (like being able to release minor & patch changes to existing consumers)
But others are less clear-- how do multiple-breaking-changes work if they fall on the same date? Does this increase surface area for regressions if new changes go to older releases?
I don't see a major advantage to be worth switching. SemVer is far more standard and is already compatible with standard node package versioning if we ever want to publish our SDK.

Regarding "monolithic PRs":
I agree this can often be a nice dev experience but there will always be inextricable race conditions. Even with calver.
For example:

Monolithic_Commit_01:

• Removes project.methodology and adds project.methodologies
• Releases 18.12.2023.api.carbonmark (or v3.0.0.api.carbonmark.com)
• Adapts the frontend to consume it.

Monolithic_PR_02 is ready to merge, Preview is passing with Preview API URL

• added a 50% discount to all projects where props.project.methodology === "AMC-001"
• it removes project.category and adds project.categories
• Releases 18.12.2023.api.carbonmark (or v3.0.0.api.carbonmark.com)
• Adapts the frontend to consume it.

In this situation:

• There are no git merge conflicts. package.json.version is not a conflict and the OpenAPI schema changes don't overlap.
• There are no type errors. project.methodology is present in the Preview URL, which was based on an earlier commit.

The issue would be only revealed if Monolithic_PR_02 pulls in the latest staging re-builds the preview API, and re-runs the codegen. Of course this could be enforced with a GHA, and automated with yet another, but also brings a few tradeoffs (more builds running more frequently, devs not catching issues earlier).

I think splitting API and frontend have a few advantages that get lost with monolithic PRs:

• Less code to review per PR
• Faster to integrate. If the API side is good to go, but the Frontend gets QA kickback, then you come back 2 days later to find you now need to integrate newer API versions and resolve conflicts.
• Division of labor between backend and frontend specialists (future thinking)

And fundamentally the dev experience is not that bad when you get in the habit of clean commits and early, frequent PRs

[0xemc]

Versioning

I've come back full circle and I tend to agree with you on continuing with Semver. There is only one major sticking point which is that we all agree that the https://github.com/KlimaDAO/klimadao/tree/staging/carbonmark-api#creating-a-hotfix process is the correct way to handle the following scenarios:

How do I make bug fixes to an api version without requiring a full alignment to the latest release of the api by it's consumer (e.g Carbonmark)?

For example:

1. carbonmark-api/v5.0.0 is the latest api version
2. Carbonmark is pointing and aligned to carbonmark-api/v2.1.0
3. A bug is identified in 2.1.0 that requires a hotfix

note: I'll add a step to the docs to merge the hotfix in to the latest release if it is necessary.

Monolithic PRs

The issue would be only revealed if Monolithic_PR_02 pulls in the latest staging re-builds the preview API, and re-runs the codegen. Of course this could be enforced with a GHA, and automated with yet another, but also brings a few tradeoffs (more builds running more frequently, devs not catching issues earlier).

The thing here is that like you said the merge conflicts and the type errors would come in when the PR is updated with the latest from staging (which is/should be a requirement to merge to staging anyway).

TLDR: As far as I can see the level of type, test and build safety is the same?

Less code to review per PR

Yes and no because these PRs are often in the context of some feature for the consumer app as well. I find myself often having to jump between them.

Faster to integrate. If the API side is good to go, but the Frontend gets QA kickback, then you come back 2 days later to find you now need to integrate newer API versions and resolve conflicts.

I think this would still be the case, if an API release has happened in the alst 2 days you would still need to integrate those changes in to your API PR no? Or do you mean from the App PR context?

Division of labor between backend and frontend specialists (future thinking)
This is true but I think should happen kind of naturally if tickets and tasks are scoped accordingly.

More Thoughts

1. I really think we're losing one of the big benefits of a monorepo by forcing the split when reviewing (since there is a lot of back and forth during reviews) especially with generated types (it sucks to have to point to deployed versions of the API or have multiple repos on your machine to host different git branches in order to generate.. if you know what I mean).
2. It's possible that an API PR gets the green light and merged but then an issue is identified while reviewing the app code which requires re-opening another PR and creating another version for the API (potentially).

Keen to hear your thoughts on this, I'm not set in stone by any means I just feel like we might be shooting ourselves in the foot potentially.

[Atmosfearful]

I really think we're losing one of the big benefits of a monorepo

This is a good point, however I argue that the real reason we lose this benefit is that I pushed us to dogfood the same versioned API that we want customers to use.

The optimal dev experience would be to have the frontend write it's own backend and deploying them together, never worrying about breaking other people's applications.

There are still other monorepo benefits, like being able to pull and run both with 1 command, or writing shared utils that can be used across the stack.

---

🧠 Side tangent, the tradeoffs are very real, but I firmly believe dogfooding is still "the way"...

• Catch API bugs, identify missing features and pain points sooner.
• Massive reduction of code duplication (assuming a BFF will do mostly the same stuff our API does).
• Unifying and standardizing types and models across the entire ecosystem (including our customer's code).
• Building full-stack competency within the team by forcing everyone to do proper API releases.
  • Set the stage for scaling out the API and backend team if when we find product market fit.

---

It's possible that an API PR gets the green light and merged but then an issue is identified

This is a good point that I didn't think about. Indeed if we could merge BE and FE together, it's significantly less turnaround in this scenario, especially for a dev in a different timezone who has to wait for someone to merge their API fix.

merge conflicts and the type errors would come in when the PR is updated with the latest from staging (which is/should be a requirement to merge to staging anyway)

I do agree that updating PRs before merging is best practice.
If we are always sure the staging API changes are integrated and the SemVer is correctly incremented I can't think of any other ways a bad merge gets in...

Last thing to think about, but I'm out of time right now-- implications of reverting a git commit on a monolithic PR? I Suspect preserving our ability to roll back only a frontend change without rolling back a BE change would be nice-to-have.

So let me try to boil this down and figure out where I'm at as far as tradeoffs

1. We want to keep dogfooding a single API (my strong opinion)
2. Monolithic PR would be a productivity boost (I agree)
3. Monolithic PR downsides are...

• Bad merge if we fail to integrate staging (a solvable problem)
• More work for lead reviewer/merger when the staging API has gotten further ahead. Maybe some QA bounceback in this case?
• In my opinion encourages bulky PRs, and discourages separation of work, planning ahead, and early integration of API changes
• Must revert both frontend and backend changes together