fix(brew): generate canonical Formula/ocm.rb alongside versioned pin (#1997)

## Summary

Users who install via `brew install open-component-model/tap/ocm`
accumulate a new keg per release (`ocm@0.40.0`, `ocm@0.41.0`, …) instead
of upgrading in place. Root cause is in this repo's release pipeline.

The publish workflow only ever generated `Formula/ocm@<version>.rb` and
pointed `Aliases/ocm` at the latest one. Brew aliases shadow same-named
formula files and resolve to the target, so `brew install …/ocm`
installed a versioned formula. Homebrew treats versioned formulas as
separate packages and installs them side-by-side, hence the pile-up.

Generate **both** files on every release:

- `Formula/ocm.rb` (class `Ocm`) — canonical, overwritten each release;
`brew install ocm` upgrades in place.
- `Formula/ocm@<version>.rb` (class `OcmAT<digits>`) — opt-in pin; users
who want a specific version run `brew install ocm@X.Y.Z`.

Drop the `Aliases/ocm` symlink creation in the workflow and remove any
stale symlink left over from earlier runs.

Companion cleanup in the tap (bumps `Formula/ocm.rb` to v0.43.0 manually
so users aren't stuck on v0.18.0 until the next release, and removes the
existing `Aliases/ocm`):
open-component-model/homebrew-tap#47

## Test plan

- [x] `go test ./...` in `hack/brew` passes
- [x] Generator output for v0.43.0 byte-identical to the existing tap
files (both `Formula/ocm.rb` and `Formula/ocm@0.43.0.rb`)
- [x] Locally tapped a synthetic tap with both generated files: `brew
info …/ocm` resolves to canonical formula 0.43.0; `brew info
…/ocm@0.43.0` still resolves to the versioned formula
- [x] Reviewer sanity-checks the workflow diff

---------

Signed-off-by: Fabian Burth <fabian.burth@sap.com>

Author: fabianburth

.github/workflows/publish-to-other-than-github.yaml

@@ -56,13 +56,10 @@ jobs:
       run: go build -o script
     - name: Update Homebrew Tap
       run: |
-        formula=$(${{ github.workspace }}/scripts/hack/brew/script \
+        ${{ github.workspace }}/scripts/hack/brew/script \
             --version ${{ env.RELEASE_VERSION }} \
             --template ${{ github.workspace }}/scripts/hack/brew/internal/ocm_formula_template.rb.tpl \
-            --outputDirectory ${{ github.workspace }}/tap/Formula)
-        mkdir -p ${{ github.workspace }}/tap/Aliases
-        cd ${{ github.workspace }}/tap/Aliases
-        ln -sf ../Formula/$(basename $formula) ./ocm
+            --outputDirectory ${{ github.workspace }}/tap/Formula
     - name: Create Pull Request
       uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
       with:
@@ -75,7 +72,6 @@ jobs:
         sign-commits: true
         add-paths: |
           Formula/*
-          Aliases/*
         body: |
           Update OCM CLI to v${{ env.RELEASE_VERSION }}.
 

hack/brew/internal/generate.go

@@ -13,10 +13,15 @@ import (
 
 const ClassName = "Ocm"
 
-// GenerateVersionedHomebrewFormula generates a Homebrew formula for a specific version,
-// architecture, and operating system. It fetches the SHA256 digest for each combination
-// and uses a template to create the formula file.
-func GenerateVersionedHomebrewFormula(
+// GenerateHomebrewFormula generates the canonical Homebrew formula and a
+// version-pinned formula for the given version. It fetches the SHA256 digest
+// for each os/arch combination and renders both files into outputDir:
+//
+//   - Formula/ocm.rb (class Ocm) — the canonical, unversioned formula. Overwritten
+//     on every release so `brew install ocm` and `brew upgrade` operate in place.
+//   - Formula/ocm@<version>.rb (class OcmAT<digits>) — opt-in pin to a specific
+//     version, for users who want `brew install ocm@X.Y.Z`.
+func GenerateHomebrewFormula(
 	version string,
 	architectures []string,
 	operatingSystems []string,
@@ -40,8 +45,16 @@ func GenerateVersionedHomebrewFormula(
 		}
 	}
 
-	if err := GenerateFormula(templateFile, outputDir, version, values, writer); err != nil {
-		return fmt.Errorf("failed to generate formula: %w", err)
+	if err := GenerateFormula(templateFile, outputDir, "ocm.rb", ClassName, values, writer); err != nil {
+		return fmt.Errorf("failed to generate canonical formula: %w", err)
+	}
+	if _, err := io.WriteString(writer, "\n"); err != nil {
+		return fmt.Errorf("failed to write separator: %w", err)
+	}
+	versionedFile := fmt.Sprintf("ocm@%s.rb", version)
+	versionedClass := fmt.Sprintf("%sAT%s", ClassName, strings.ReplaceAll(version, ".", ""))
+	if err := GenerateFormula(templateFile, outputDir, versionedFile, versionedClass, values, writer); err != nil {
+		return fmt.Errorf("failed to generate versioned formula: %w", err)
 	}
 
 	return nil
@@ -67,33 +80,33 @@ func FetchDigestFromGithubRelease(releaseURL, version, targetOs, arch string) (_
 	return strings.TrimSpace(string(digestBytes)), nil
 }
 
-// GenerateFormula generates the Homebrew formula file using the provided template and values.
-func GenerateFormula(templateFile, outputDir, version string, values map[string]string, writer io.Writer) error {
+// GenerateFormula renders templateFile into outputDir/outputFile using the
+// provided className for the Ruby class and values for template substitution.
+func GenerateFormula(templateFile, outputDir, outputFile, className string, values map[string]string, writer io.Writer) error {
 	tmpl, err := template.New(filepath.Base(templateFile)).Funcs(template.FuncMap{
 		"classname": func() string {
-			return fmt.Sprintf("%sAT%s", ClassName, strings.ReplaceAll(version, ".", ""))
+			return className
 		},
 	}).ParseFiles(templateFile)
 	if err != nil {
 		return fmt.Errorf("failed to parse template: %w", err)
 	}
 
-	outputFile := fmt.Sprintf("ocm@%s.rb", version)
 	if err := ensureDirectory(outputDir); err != nil {
 		return err
 	}
 
-	versionedFormula, err := os.Create(filepath.Join(outputDir, outputFile))
+	formula, err := os.Create(filepath.Join(outputDir, outputFile))
 	if err != nil {
 		return fmt.Errorf("failed to create output file: %w", err)
 	}
-	defer versionedFormula.Close()
+	defer formula.Close()
 
-	if err := tmpl.Execute(versionedFormula, values); err != nil {
+	if err := tmpl.Execute(formula, values); err != nil {
 		return fmt.Errorf("failed to execute template: %w", err)
 	}
 
-	if _, err := io.WriteString(writer, versionedFormula.Name()); err != nil {
+	if _, err := io.WriteString(writer, formula.Name()); err != nil {
 		return fmt.Errorf("failed to write output file path: %w", err)
 	}
 

hack/brew/internal/generate_test.go

@@ -18,7 +18,7 @@ var tplFile []byte
 //go:embed testdata/expected_formula.rb
 var expectedResolved []byte
 
-func TestGenerateVersionedHomebrewFormula(t *testing.T) {
+func TestGenerateHomebrewFormula(t *testing.T) {
 	version := "1.0.0"
 	architectures := []string{"amd64", "arm64"}
 	operatingSystems := []string{"darwin", "linux"}
@@ -39,7 +39,7 @@ func TestGenerateVersionedHomebrewFormula(t *testing.T) {
 
 	var buf bytes.Buffer
 
-	err := GenerateVersionedHomebrewFormula(
+	err := GenerateHomebrewFormula(
 		version,
 		architectures,
 		operatingSystems,
@@ -52,29 +52,38 @@ func TestGenerateVersionedHomebrewFormula(t *testing.T) {
 		t.Fatalf("expected no error, got %v", err)
 	}
 
-	file := buf.String()
-
-	fi, err := os.Stat(file)
-	if err != nil {
-		t.Fatalf("expected no error, got %v", err)
+	paths := strings.Split(strings.TrimSpace(buf.String()), "\n")
+	if len(paths) != 2 {
+		t.Fatalf("expected 2 generated paths, got %d: %q", len(paths), paths)
 	}
-	if fi.Size() == 0 {
-		t.Fatalf("expected file to be non-empty")
-	}
-	if filepath.Ext(file) != ".rb" {
-		t.Fatalf("expected file to have .rb extension")
-	}
-	if !strings.Contains(file, version) {
-		t.Fatalf("expected file to contain version")
+
+	for _, file := range paths {
+		fi, err := os.Stat(file)
+		if err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if fi.Size() == 0 {
+			t.Fatalf("expected file to be non-empty")
+		}
+		if filepath.Ext(file) != ".rb" {
+			t.Fatalf("expected file to have .rb extension")
+		}
 	}
 
-	data, err := os.ReadFile(file)
+	canonical, err := os.ReadFile(paths[0])
 	if err != nil {
 		t.Fatalf("expected no error, got %v", err)
 	}
 
-	if string(data) != string(expectedResolved) {
-		t.Fatalf("expected %s, got %s", string(expectedResolved), string(data))
+	if string(canonical) != string(expectedResolved) {
+		t.Fatalf("expected %s, got %s", string(expectedResolved), string(canonical))
+	}
+
+	if filepath.Base(paths[0]) != "ocm.rb" {
+		t.Fatalf("expected first generated file to be ocm.rb, got %s", paths[0])
+	}
+	if filepath.Base(paths[1]) != "ocm@1.0.0.rb" {
+		t.Fatalf("expected second generated file to be ocm@1.0.0.rb, got %s", paths[1])
 	}
 }
 
@@ -114,15 +123,15 @@ end`
 
 	var buf bytes.Buffer
 
-	if err := GenerateFormula(templateFile, outputDir, "1.0.0", values, &buf); err != nil {
+	if err := GenerateFormula(templateFile, outputDir, "ocm.rb", "Ocm", values, &buf); err != nil {
 		t.Fatalf("expected no error, got %v", err)
 	}
 
 	if buf.String() == "" {
 		t.Fatalf("expected non-empty output")
 	}
 
-	outputFile := filepath.Join(outputDir, "ocm@1.0.0.rb")
+	outputFile := filepath.Join(outputDir, "ocm.rb")
 	if _, err := os.Stat(outputFile); os.IsNotExist(err) {
 		t.Fatalf("expected output file to exist")
 	}

hack/brew/internal/testdata/expected_formula.rb

@@ -1,7 +1,7 @@
 # typed: false
 # frozen_string_literal: true
 
-class OcmAT100 < Formula
+class Ocm < Formula
   desc "The OCM CLI makes it easy to create component versions and embed them in build processes."
   homepage "https://ocm.software/"
   version "1.0.0"

hack/brew/main.go

@@ -28,7 +28,7 @@ func main() {
 		log.Fatalf("version is required")
 	}
 
-	if err := internal.GenerateVersionedHomebrewFormula(*version,
+	if err := internal.GenerateHomebrewFormula(*version,
 		strings.Split(*architecturesRaw, ","),
 		strings.Split(*operatingSystemsRaw, ","),
 		*releaseURL,