Implement standardized versioning

VERSION

@@ -0,0 +1,23 @@
+# This file is used to determine the semantic version for the build of Grafana
+# Alloy being constructed is.
+#
+# For builds produced against release branches, the major and minor version
+# indicated in this file match the release branch. For example, for the branch
+# release/v1.0, this file will report v1.0.0. The patch version indicated by this
+# file syncs with the patch release being planned. For example, if a v1.0.1
+# patch release is planned, this file will report v1.0.1 before that release is
+# produced.
+#
+# For builds produced against main branches, the major and minor version
+# reported by this file matches the next minor or major version to be released.
+# For example, if v1.0.0 was just released, this file (in the main branch) will
+# report v1.1.0, the next release planned.
+#
+# The string in this file MUST be a valid semantic version prefixed with "v",
+# without any pre-release or build information.
+#
+# This file is ignored when building binaries from a Git tag.
+#
+# Lines starting with "#" and blank lines are ignored.
+
+v1.0.0

docs/developer/release/1-create-release-branch.md

@@ -24,3 +24,7 @@ Patch Releases for that major pr minor version of the agent.
 
     > **NOTE**: Don't create any other branches that are prefixed with `release` when creating PRs or
     those branches will collide with our automated release build publish rules.
+
+3. Open a PR against `main` to update the VERSION file at the root of the
+   repository to the next minor release planned. For example, if you have just
+   created `release/v1.0`, then VERSION should be updated to `v1.1.0`.

docs/developer/release/3-update-version-in-code.md

@@ -22,18 +22,6 @@ The project must be updated to reference the upcoming release tag whenever a new
 
     2. Move the unreleased changes we want to add to the release branch from `Main (unreleased)` to `VERSION (YYYY-MM-DD)`.
 
-    3. Update appropriate places in the codebase that have the previous version with the new version determined above.
-
-        First update `tools/gen-versioned-files/agent-version.txt` with the new `VERSION` and run:
-
-        ```
-        make generate-versioned-files
-        ```
-
-        Next, commit the changes (including those to `tools/gen-versioned-files/agent-version.txt`, as a workflow will use this version to ensure that the templates and generated files are in sync).
-
-        * Do **not** update the `operations/helm` directory. It is updated independently from Agent releases.
-
 3. Create a PR to merge to main (must be merged before continuing).
 
     - Release Candidate example PR [here](https://github.com/grafana/agent/pull/3065)
@@ -50,6 +38,20 @@ The project must be updated to reference the upcoming release tag whenever a new
 
     Delete the `Main (unreleased)` header and anything underneath it as part of the cherry-pick. Alternatively, do it after the cherry-pick is completed.
 
+6. **If you are creating a patch release,** ensure that the file called `VERSION` in your branch matches the version being published, without any release candidate or build information:
+
+   > **NOTE**: Only perform this step for patch releases, and make sure that
+   > the change is not pushed to the main branch.
+
+   After updating `VERSION`, run:
+
+   ```bash
+   make generate-versioned-files
+   ```
+
+   Next, commit the changes (including those to `VERSION`, as a workflow will use this version to ensure that the templates and generated files are in sync).
+
+
 6. Create a PR to merge to `release/VERSION_PREFIX` (must be merged before continuing).
 
     - Release Candidate example PR [here](https://github.com/grafana/agent/pull/3066)

docs/sources/_index.md

@@ -4,7 +4,7 @@ title: Grafana Alloy
 description: Grafana Alloy is a flexible, performant, vendor-neutral, telemetry collector
 weight: 350
 cascade:
-  ALLOY_RELEASE: $ALLOY_VERSION
+  ALLOY_RELEASE: v1.0.0
   OTEL_VERSION: v0.87.0
   PRODUCT_NAME: Grafana Alloy
   PRODUCT_ROOT_NAME: Alloy

internal/build/build.go

@@ -1,6 +1,9 @@
 package build
 
 import (
+	"strings"
+
+	"github.com/blang/semver/v4"
 	"github.com/prometheus/client_golang/prometheus"
 	"github.com/prometheus/common/version"
 )
@@ -18,9 +21,27 @@ var (
 )
 
 func init() {
+	Version = normalizeVersion(Version)
 	injectVersion()
 }
 
+// normalizeVersion normalizes the version string to always contain a "v"
+// prefix. If version cannot be parsed as a semantic version, version is returned unmodified.
+//
+// if version is empty, normalizeVersion returns "v0.0.0".
+func normalizeVersion(version string) string {
+	version = strings.TrimSpace(version)
+	if version == "" {
+		return "v0.0.0"
+	}
+
+	parsed, err := semver.ParseTolerant(version)
+	if err != nil {
+		return version
+	}
+	return "v" + parsed.String()
+}
+
 func injectVersion() {
 	version.Version = Version
 	version.Revision = Revision

internal/build/build_test.go

@@ -0,0 +1,33 @@
+package build
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func Test_normalizeVersion(t *testing.T) {
+	tt := []struct {
+		input  string
+		expect string
+	}{
+		{"", "v0.0.0"},
+		{"v1.2.3", "v1.2.3"},
+		{"1.2.3", "v1.2.3"},
+		{"1.2.3+SHA", "v1.2.3+SHA"},
+		{"v1.2.3+SHA", "v1.2.3+SHA"},
+		{"1.2.3-rc.1", "v1.2.3-rc.1"},
+		{"v1.2.3-rc.1", "v1.2.3-rc.1"},
+		{"1.2.3-rc.1+SHA", "v1.2.3-rc.1+SHA"},
+		{"v1.2.3-rc.1+SHA", "v1.2.3-rc.1+SHA"},
+		{"not_semver", "not_semver"},
+	}
+
+	for _, tc := range tt {
+		actual := normalizeVersion(tc.input)
+		assert.Equal(t, tc.expect, actual,
+			"Expected %q to normalize to %q, got %q",
+			tc.input, tc.expect, actual,
+		)
+	}
+}

tools/gen-versioned-files/gen-versioned-files.sh

@@ -1,20 +1,20 @@
 #!/bin/sh
-AGENT_VERSION=$(cat ./tools/gen-versioned-files/agent-version.txt | tr -d '\n')
+ALLOY_VERSION=$(sed -e '/^#/d' -e '/^$/d' VERSION | tr -d '\n')
 
-if [ -z "$AGENT_VERSION" ]; then
-    echo "AGENT_VERSION can't be found. Are you running this from the repo root?"
+if [ -z "$ALLOY_VERSION" ]; then
+    echo "ALLOY_VERSION can't be found. Are you running this from the repo root?"
     exit 1
 fi
 
-versionMatcher='^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[0-9]+)?$'
+versionMatcher='^v[0-9]+\.[0-9]+\.[0-9]$'
 
-if ! echo "$AGENT_VERSION" | grep -Eq "$versionMatcher"; then
-    echo "AGENT_VERSION env var is not in the correct format. It should be in the format of vX.Y.Z or vX.Y.Z-rc.N"
+if ! echo "$ALLOY_VERSION" | grep -Eq "$versionMatcher"; then
+    echo "ALLOY_VERSION env var is not in the correct format. It should be in the format of vX.Y.Z"
     exit 1
 fi
 
 templates=$(find . -type f -name "*.t" -not -path "./.git/*")
 for template in $templates; do
     echo "Generating ${template%.t}"
-    sed -e "s/\$AGENT_VERSION/$AGENT_VERSION/g" < "$template" > "${template%.t}"
+    sed -e "s/\$ALLOY_VERSION/$ALLOY_VERSION/g" < "$template" > "${template%.t}"
 done

tools/image-tag

@@ -1,21 +1,34 @@
 #!/usr/bin/env bash
+#
+# image-tag determines which version to embed into a built image.
+#
+# It prefers the following in precedence order:
+#
+# 1. RELEASE_TAG environment variable
+# 2. The Git tag of the current commit (if any)
+# 3. The version in the VERSION file, suffixed with -devel plus build
+#    information.
 set -o errexit
 set -o pipefail
 
+VERSION=$(sed -e '/^#/d' -e '/^$/d' VERSION | tr -d '\n')
+DETECTED_TAG=$(git describe --match 'v*' --exact-match 2>/dev/null || echo -n "")
+
 if [ ! -z "${RELEASE_TAG}" ]; then
   echo ${RELEASE_TAG}
   exit 0
+elif [ ! -z "${DETECTED_TAG}" ]; then
+  echo ${DETECTED_TAG}
+  exit 0
 fi
 
 set -o nounset
 
-WIP=$(git diff --quiet || echo '-WIP')
-BRANCH=$(git rev-parse --abbrev-ref HEAD | sed 's#/#-#g')
-
-# When 7 chars are not enough to be unique, git automatically uses more.
-# We are forcing to 7 here, as we are doing for grafana/grafana as well.
-SHA=$(git rev-parse --short=7 HEAD | head -c7)
-
-# If this is a tag, use it, otherwise use <branch>-<hash>
-TAG=$(git describe --exact-match 2> /dev/null || echo "${BRANCH}-${SHA}")
-echo ${TAG}${WIP}
+if [[ -z $(git status -s) ]]; then
+  # There are no changes; report version as VERSION-devel+SHA.
+  SHA=$(git rev-parse --short HEAD)
+  echo ${VERSION}-devel+${SHA}
+else
+  # Git is dirty; tag as VERSION-devel+wip.
+  echo ${VERSION}-devel+wip
+fi