Skip to content

docs: document our branching / versioning process #408

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Feb 10, 2025
Merged

docs: document our branching / versioning process #408

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions docs/project-management/branching-and-versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Branching and versioning strategy

## Versioning

kubebuilder-declarative-pattern is a library, that works with controller-runtime and kubernetes.

We follow semantic versioning, similar to other tooling in the kubernetes ecosystem.

Because both controller-runtime and client-go introduce changes that require code changes, we follow their versioning.
Specifically we align with the controller-runtime version, which itself aligns with kubernetes versioning.

Thus:

| kdp version | controller-runtime version | client-go version |
|---|---|---|
| v0.20 | v0.20 | v0.32 |
| v0.19 | v0.19 | v0.31 |
| v0.18 | v0.18 | v0.30 |
| ... | ... | ... |
| v0.x | v0.x | v0.x+12 |
Comment on lines +14 to +20
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should have the versioning scheme allow for releasing multiple kdp versions per controller-runtime/client-go version; easiest is probably just to increment the patch, but we might want to explicitly call that out here.

Copy link
Contributor Author

@justinsb justinsb Jan 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll try to expand. My 2c is that while in theory we might want to make breaking changes more often than client-go releases, in practice I don't think that's very likely, and I think that would make the library difficult to consume. So agree that we should have multiple patch releases - agree that's not clear. But those patches should avoid breaking changes.

Note that we can still make as many breaking changes as we want on the main branch; we just only release a batch of breaking changes every 4 months or so. (And of course the ideal number of breaking changes is zero :-) )

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added a small paragraph here to describe this - thanks for the suggestion!


If we need to release multiple versions of kdp for a single version of controller-runtime (for example if we want to fix a bug),
we use patch versions for that.
We want to avoid breaking changes, and we will only make breaking changes on minor version bumps (as far as possible).

## Branches

We maintain a `release-0.x` branch for the kdp major version `0.x`. Patch versions are cherry-picked to the branch and released.

We cut the release branch with the beta release (i.e. we create `release-1.100` when we tag `1.100.0-beta.1`).

Before beta releases, the master branch is for the next minor version. If we tag a version, it would be (for example) `1.101.0-alpha.1` (and then `1.101.0-alpha.2` etc), assuming the most recent release branch was `1.100`
Loading