CLOUDP-345379: File-based release version control (#2709)

* Add a file-based approach to control release version

* unify major-version check

* update release documentation

* Check the release version match expected next version

* fix bump-version-file target

* improve docs

Author: helderjs

.github/actions/build-push-image/action.yaml

@@ -1,33 +1,22 @@
 name: Build Container Image
 description: Builds the operator container image for the given architecture
 inputs:
-  get-existing-cache:
-    description: 'Get cache from the previous build'
-    required: false
-    default: 'false'
   platforms:
     description: The list of platforms for which the image will be built
     required: true
   version:
-    description: The version of the operator will be built
-    required: true
-  certified_version:
-    description: The certified version of the operator will be built
-    default: ''
-    required: false
-  repository:
-    description: The name of repository to build image
+    description: The version of the operator binary will be built
     required: true
   file:
     description: Name of the dockerfile relative to context
     required: false
     default: Dockerfile
   docker_username:
     description: The username to access the docker registry
-    required: true
+    required: false
   docker_password:
     description: The password to access the docker registry
-    required: true
+    required: false
   push_to_docker:
     description: Push image to docker.io
     required: false

.github/actions/set-tag/entrypoint.sh

@@ -17,12 +17,13 @@ set -eou pipefail
 
 git config --global --add safe.directory /github/workspace
 
-# Get the full commit hash and shorten to 7 characters
+commit_id=$(git rev-parse --short HEAD)
+
+# If commit passed shorten to 8 characters
 full_commit_sha="${INPUT_COMMIT_SHA:-}"
-if [ -z "$full_commit_sha" ]; then
-  full_commit_sha=$(git rev-parse HEAD)
+if [ -n "$full_commit_sha" ]; then
+  commit_id=$(echo "$full_commit_sha" | cut -c1-8)
 fi
-commit_id=$(echo "$full_commit_sha" | cut -c1-7)
 
 # Get the full branch name
 branch_name="${INPUT_BRANCH_NAME:-}"

.github/workflows/openshift-upgrade-test.yaml

@@ -33,9 +33,6 @@ jobs:
         with:
           ref: ${{github.event.pull_request.head.sha}}
           fetch-depth: 0 # required for tags
-      - name: Prepare tag
-        id: prepare
-        uses: ./.github/actions/set-tag
       - name: Install devbox
         uses: jetify-com/[email protected]
         with:

.github/workflows/release-image.yml

@@ -76,17 +76,31 @@ jobs:
       RELEASE_TYPE: ${{ github.event.inputs.release_type }}
     outputs:
       repo: ${{ steps.compute.outputs.repo }}
+      version: ${{ steps.read_version.outputs.version }}
     steps:
-     - name: Compute
-       id: compute
-       run: |
-          if [ "${RELEASE_TYPE}" == "official-release" ]; then
-            echo "Setting official release repo mongodb/mongodb-atlas-kubernetes-operator"
-            echo "repo=mongodb/mongodb-atlas-kubernetes-operator" | tee -a $GITHUB_OUTPUT
-          else
-            echo "Setting pre-release repo mongodb/mongodb-atlas-kubernetes-operator-prerelease"
-            echo "repo=mongodb/mongodb-atlas-kubernetes-operator-prerelease" | tee -a $GITHUB_OUTPUT
-          fi
+    - name: Compute
+      id: compute
+      run: |
+        if [ "${RELEASE_TYPE}" == "official-release" ]; then
+          echo "Setting official release repo mongodb/mongodb-atlas-kubernetes-operator"
+          echo "repo=mongodb/mongodb-atlas-kubernetes-operator" | tee -a $GITHUB_OUTPUT
+        else
+          echo "Setting pre-release repo mongodb/mongodb-atlas-kubernetes-operator-prerelease"
+          echo "repo=mongodb/mongodb-atlas-kubernetes-operator-prerelease" | tee -a $GITHUB_OUTPUT
+        fi
+    - name: Read the next release version
+      id: read_version
+      env:
+        INPUT_VERSION: ${{ github.event.inputs.version }}
+      run: |
+        VERSION=$(jq -r '.next' version.json)
+        
+        if [[ "$INPUT_VERSION" != "$VERSION" ]]; then
+          echo "::error::Input version '$INPUT_VERSION' does not match the expected 'next' version '$VERSION' from version.json."
+          exit 1
+        fi
+        
+        echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
 
   # Release-image: Created and uploads a release for the specified operator version given in the image_sha
   # Note, with new releases, all the release artifacts will be stored within docs/releases/{version}
@@ -98,7 +112,7 @@ jobs:
     - image2commit
     - compute-repo
     env:
-      VERSION: ${{ github.event.inputs.version }}
+      VERSION: ${{ needs.compute-repo.outputs.version }}
       RELEASE_TAG: v${{ github.event.inputs.version }}
       AUTHORS: ${{ github.event.inputs.authors }}
       IMAGE_SHA: ${{ github.event.inputs.image_sha }}
@@ -238,6 +252,10 @@ jobs:
         run: |
           devbox run -- 'make build-licenses.csv'
 
+      - name: Bump version.json
+        run: |
+          devbox run -- 'make bump-version-file'
+
       # Create PR on release branch with all updates generated
       - name: Create release pr with all updated artefacts
         env:

.github/workflows/test-e2e.yml

@@ -15,6 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       test_matrix: ${{ steps.compute.outputs.matrix }}
+      next_version: ${{ steps.read_version.outputs.version }}
     steps:
       - uses: actions/checkout@v5
 
@@ -26,9 +27,14 @@ jobs:
             matrix='["v1.31.9-kind", "v1.33.2-kind"]'
           fi
           echo "matrix=${matrix}" >> "${GITHUB_OUTPUT}"
-
+      - name: Read the next release version
+        id: read_version
+        run: |
+          VERSION=$(jq -r '.next' version.json)
+          echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
   prepare-e2e-image:
     runs-on: ubuntu-latest
+    needs: [prepare-e2e]
     outputs:
       image_url: ${{ steps.set_image_url.outputs.image_url }}
     env:
@@ -58,8 +64,7 @@ jobs:
         uses: ./.github/actions/build-push-image
         with:
           file: fast.Dockerfile
-          repository: ${{ env.REPO }}
-          version: ${{ steps.set_tag.outputs.tag }}
+          version: ${{ needs.prepare-e2e.outputs.next_version }}
           tags: ${{ steps.set_image_url.outputs.image_url }}
           platforms: linux/amd64,linux/arm64
           push_to_docker: false

.github/workflows/tests-e2e2.yaml

@@ -142,9 +142,6 @@ jobs:
         with:
           enable-cache: 'true'
 
-      - name: Prepare tag
-        id: prepare
-        uses: ./.github/actions/set-tag
       - name: Set properties
         id: properties
         run: |

.github/workflows/tests-selectable.yaml

@@ -28,20 +28,18 @@ jobs:
       int_matrix: ${{ steps.set-matrix.outputs.int_matrix }}
       e2e_matrix: ${{ steps.set-matrix.outputs.e2e_matrix }}
       e2e_gov_matrix: ${{ steps.set-matrix.outputs.e2e_gov_matrix }}
+      next_version: ${{ steps.read_version.outputs.version }}
     steps:
       - name: Checkout Code
         uses: actions/checkout@v5
         with:
           ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.branchName || github.event.pull_request.head.sha }}
-
       - name: Setup GO
         uses: actions/setup-go@v6
         with:
           go-version-file: "${{ github.workspace }}/go.mod"
-
       - name: Install Ginkgo
         run: go install github.com/onsi/ginkgo/v2/ginkgo@latest
-
       - name: Get test labels from PR or input
         env:
           TEST_LABELS: ${{ github.event.inputs.testLabels }}
@@ -62,7 +60,6 @@ jobs:
             }
             console.log("Not a PullRequest or WorkflowDispatch event skipping");
             return [];
-
       - name: List available Ginkgo test labels
         id: fetch-labels
         run: |
@@ -74,7 +71,6 @@ jobs:
           
           echo "Available Integration Tests: $INT_LABELS"
           echo "Available E2E Tests: $E2E_LABELS"
-
       - name: Compute Test Matrix
         id: set-matrix
         env:
@@ -92,6 +88,11 @@ jobs:
           echo "int_matrix=$(cat result.json | jq -c .int)" >> $GITHUB_OUTPUT
           echo "e2e_matrix=$(cat result.json | jq -c .e2e)" >> $GITHUB_OUTPUT
           echo "e2e_gov_matrix=$(cat result.json | jq -c .e2e_gov)" >> $GITHUB_OUTPUT
+      - name: Read the next release version
+        id: read_version
+        run: |
+          VERSION=$(jq -r '.next' version.json)
+          echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
 
   compute:
     needs: detect-tests
@@ -138,8 +139,7 @@ jobs:
         uses: ./.github/actions/build-push-image
         with:
           file: fast.Dockerfile
-          repository: ghcr.io/${{ env.REPOSITORY }}
-          version: ${{ steps.prepare.outputs.tag }}
+          version: ${{ needs.detect-tests.outputs.next_version }}
           tags: ghcr.io/${{ env.REPOSITORY }}:${{ steps.prepare.outputs.tag }}
           platforms: linux/amd64
           push_to_docker: false
@@ -178,7 +178,7 @@ jobs:
         uses: ./.github/actions/gen-install-scripts
         with:
           IMAGE_URL: ${{ env.GHCR_REPO }}:${{ steps.prepare.outputs.tag }}
-          VERSION: ${{ steps.prepare.outputs.tag }}
+          VERSION: ${{ needs.detect-tests.outputs.next_version }}
           ENV: dev
 
       - name: Change URL for the test
@@ -207,8 +207,7 @@ jobs:
         uses: ./.github/actions/build-push-image
         with:
           file: fast.Dockerfile
-          repository: ${{ env.GHCR_BUNDLES_REPO }}
-          version: ${{ steps.prepare.outputs.tag }}
+          version: ${{ needs.detect-tests.outputs.next_version }}
           tags: ${{ env.GHCR_BUNDLES_REPO }}:${{ steps.prepare.outputs.tag }}
           platforms: linux/amd64
           push_to_docker: false
@@ -295,7 +294,7 @@ jobs:
         uses: ./.github/actions/gen-install-scripts
         with:
           IMAGE_URL: ${{ env.GHCR_REPO }}:${{ steps.prepare.outputs.tag }}
-          VERSION: ${{ steps.prepare.outputs.tag }}
+          VERSION: ${{ needs.detect-tests.outputs.next_version }}
           ENV: dev
 
       - name: Change path for the test

Makefile

@@ -11,15 +11,19 @@ DOCKER_SBOM_PLUGIN_VERSION=0.6.1
 # To re-generate a bundle for another specific version without changing the standard setup, you can:
 # - use the VERSION as arg of the bundle target (e.g make bundle VERSION=0.0.2)
 # - use environment variables to overwrite this value (e.g export VERSION=0.0.2)
+VERSION_FILE=version.json
 VERSION ?= $(shell git describe --always --tags --dirty --broken | cut -c 2-)
+BUILDTIME ?= $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
+GITCOMMIT ?= $(shell git rev-parse --short HEAD 2> /dev/null || true)
+
+VERSION_PACKAGE = github.com/mongodb/mongodb-atlas-kubernetes/v2/internal/version
 
 # LD_FLAGS
-LD_FLAG_SET_VERSION = -X github.com/mongodb/mongodb-atlas-kubernetes/v2/internal/version.Version=$(VERSION)
-LD_FLAGS_SET_EXPERIMENTAL = -X github.com/mongodb/mongodb-atlas-kubernetes/v2/internal/version.Experimental=$(EXPERIMENTAL)
+LD_FLAGS := -X $(VERSION_PACKAGE).Version=$(VERSION)
+LD_FLAGS += -X $(VERSION_PACKAGE).GitCommit=$(GITCOMMIT)
+LD_FLAGS += -X $(VERSION_PACKAGE).BuildTime=$(BUILDTIME)
 ifdef EXPERIMENTAL
-LD_FLAGS = $(LD_FLAGS_SET_EXPERIMENTAL) $(LD_FLAG_SET_VERSION)
-else
-LD_FLAGS = $(LD_FLAG_SET_VERSION)
+LD_FLAGS += -X $(VERSION_PACKAGE).Experimental=$(EXPERIMENTAL)
 endif
 
 # NEXT_VERSION represents a version that is higher than anything released
@@ -444,8 +448,10 @@ actions.txt: .github/workflows/ ## List GitHub Action dependencies
 
 .PHONY: check-major-version
 check-major-version: ## Check that VERSION starts with MAJOR_VERSION
-	@[[ $(VERSION) == $(MAJOR_VERSION).* ]] && echo "Version OK" || \
-	(echo "Bad major version for $(VERSION) expected $(MAJOR_VERSION)"; exit 1)
+	@VERSION_MAJOR=$$(echo "$(VERSION)" | cut -d. -f1 | sed 's/v//'); \
+	CURRENT_MAJOR=$$(jq -r '.current' $(VERSION_FILE) | cut -d. -f1); \
+	[ "$$VERSION_MAJOR" = "$$CURRENT_MAJOR" ] || \
+	(echo "Bad major version for $$VERSION expected $$CURRENT_MAJOR"; exit 1)
 
 tools/makejwt/makejwt: tools/makejwt/*.go
 	cd tools/makejwt && go test . && go build .
@@ -648,4 +654,13 @@ tools/scandeprecation/scandeprecation: tools/scandeprecation/*.go
 .PHONY: slack-deprecations
 slack-deprecations: tools/scandeprecation/scandeprecation tools/githubjobs/githubjobs
 	@echo "Computing and sending deprecation report to Slack..."
-	GH_RUN_ID=$(GH_RUN_ID) ./tools/githubjobs/githubjobs | grep "javaMethod" | ./tools/scandeprecation/scandeprecations | ./scripts/slackit.sh $(SLACK_WEBHOOK)
+	GH_RUN_ID=$(GH_RUN_ID) ./tools/githubjobs/githubjobs | grep "javaMethod" | ./tools/scandeprecation/scandeprecations | ./scripts/slackit.sh $(SLACK_WEBHOOK)
+
+.PHONY: bump-version-file
+bump-version-file:
+	@echo "Bumping version in $(VERSION_FILE)..."
+
+	jq '(.next | split(".") | map(tonumber) | .[1] += 1 | .[2] = 0 | map(tostring) | join(".")) as $$new_next | .current = .next | .next = $$new_next' $(VERSION_FILE) > $(VERSION_FILE).tmp && mv $(VERSION_FILE).tmp $(VERSION_FILE)
+
+	@echo "Version updated successfully:"
+	@cat $(VERSION_FILE)

docs/dev/release.md

@@ -23,6 +23,16 @@ At least **one** (1) week before the release the Kubernetes Version testing matr
 
 Please refer to the [CI documentation](ci.md#kubernetes-version-matrix) and submit a pull request, example: https://github.com/mongodb/mongodb-atlas-kubernetes/pull/2161 or https://github.com/mongodb/mongodb-atlas-kubernetes/pull/2082.
 
+## A Note on Versioning with `version.json`
+
+The `version.json` file is the definitive **source of truth** for managing software versions in this project.
+
+* **Source of Truth**: The file contains two primary fields: **`current`**, which reflects the latest stable version that has been released, and **`next`**, which designates the version targeted for the upcoming release.
+
+* **Automatic Updates for next Releases**: After a successful release, the CI pipeline will **automatically** update `version.json`. The `current` field is set to the version that was just released, and the `next` field is incremented to the next minor version (e.g., `2.11.0` would become `2.12.0`, or `2.11.4` would become `2.12.0`).
+
+* **Manual Updates for Patch Releases**: Creating a **patch release** (e.g., `v2.10.1`) is a deliberate exception to the automated process. To prepare for a patch, you must **manually** update the `next` field to the exact patch version via a Pull Request (PR). This manual step ensures the release workflow targets the specific patch instead of accidentally creating the next minor release.
+
 ## Release Notes
 
 - Create a draft of the release notes in a Google Document and share with Product and the Docs team.
@@ -42,26 +52,23 @@ You will be prompted to enter:
 
 | Input       | Description                                                                                         | Required | Default  | Example                               |
 |-------------|-----------------------------------------------------------------------------------------------------|----------|----------|---------------------------------------|
-| `version`   | The version to be released, including the `v` prefix                                                | Yes      | None     | `v1.10.3`                             |
 | `authors`   | A comma-separated list of MongoDB email addresses responsible for the release                       | Yes      | None     | `[email protected],[email protected]`   |
 | `image_sha` | The 7-character Git commit SHA used for the promoted image, or `'latest'` for the most recent       | No       | `latest` | `3e79a3f`.                            |
 
-The inputs `version` and `authors` must be filled out every time you trigger the release workflow. The `image_sha` is optional and defaults to `latest` if left empty.
+The input `authors` must be filled out every time you trigger the release workflow. The `image_sha` is optional and defaults to `latest` if left empty.
 
 The `image_sha` corresponds exactly to the 7-character Git commit SHA used to build the operator image; for example, `image_sha: 3e79a3f` means the image was built from Git commit `3e79a3f`. Using `latest` as the `image_sha` means the workflow will release the most recently promoted and tested operator image—not necessarily the latest Git commit—and when `latest` is used, the workflow will echo the corresponding Git commit during the internal steps so the user knows exactly which source is being released.
 
 ### Example Release Input
 
 ```yaml
-version: v1.10.3
 authors: [email protected],[email protected]
 image_sha: 3e79a3f
 ```
 
 or
 
 ```yaml
-version: v1.10.3
 authors: [email protected],[email protected]
 image_sha: latest
 ```
@@ -332,10 +339,12 @@ And use the URL there to set `OPENSHIFT_UPGRADE_SERVER_API` so that openshift up
 
 ### Major version issues when executing the "Create Release Branch" workflow
 
-The release creation will fail if the file `major-version` contents does not match the major version to be released. This file explicitly means the upcoming release is for a particular major version, with potential breaking changes. This allows us to:
+The release creation will fail if the major version of the release you're creating is incompatible with the `current` version defined in the `version.json` file. This file acts as the single source of truth for the codebase's version, which helps prevent mistakes.
+
+This check allows us to:
 
-1. Notice if we forgot to update the `major-version` file before releasing the next major version.
-2. Notice if we tried to re-release an older major version when the code is already prepared for the next major version.
-3. Skip some tests, like `helm update`, when crossing from one major version to the next, as such test is not expected to work across incompatible major version upgrades.
+1.  **Prevent Mismatches**: It stops the workflow if the version being released (e.g., `v3.0.0`) has a different major version than what the codebase expects (e.g., `current` is `v2.11.0`).
+2.  **Avoid Incorrect Patching**: It stops you from accidentally trying to release a patch for an older major version (e.g., `v1.2.3`) when the codebase has already moved on to a new major version.
+3.  **Skip Tests**: Certain tests that are expected to fail, like Helm upgrades, they should be skipped.
 
-If the create release branch job fails due an error such as `Bad major version for X... expected Y..`, review whether or not the `major-version` file was updated as expected. Check as well you are not trying to release a patch for the older major version from the new major version codebase.
+If the "Create Release Branch" job fails with an error like `Bad major version for X... expected Y...`, you should review the `current` field in `version.json`. Ensure it correctly reflects the codebase's state and is compatible with the version you intend to release.