[Bug]: Brew don't install the latest official release: 0.9.0

[cmoulliard]

What is your environment, configuration, and command?

OS: macOS: 14.7.4-arm64
Tool: 
/opt/homebrew/bin/brew config
HOMEBREW_VERSION: 4.4.24-201-g2462e40
ORIGIN: https://github.com/Homebrew/brew

What did you do and What did you see instead?

The users don't get the latest official release of idpbuilder when they install or upgrade our formula.

Example

❯ idp version
idpbuilder 0.9.0-nightly.20250212 go1.22.12 darwin/arm64

❯ brew upgrade idpbuilder
==> Upgrading 1 outdated package:
cnoe-io/tap/idpbuilder 0.9.0-nightly.20250212 -> 0.10.0-nightly.20250226
==> Fetching cnoe-io/tap/idpbuilder
==> Downloading https://github.com/cnoe-io/idpbuilder/releases/download/v0.10.0-nightly.20250226/idpbuilder-darwin-arm64.tar.gz
==> Downloading from https://objects.githubusercontent.com/github-production-release-asset-2e65be/697890131/44965a14-b2ef-4379-a3b7-f861ad43c97e?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-A
############################################################################################################################################################################## 100.0%
==> Upgrading cnoe-io/tap/idpbuilder
  0.9.0-nightly.20250212 -> 0.10.0-nightly.20250226

The latest official release is now 0.9.0 but brew installs the nightly build 0.10.0-nightly.xxxxxxx as that corresponds to the latest formula published having as version: https://github.com/cnoe-io/homebrew-tap/blob/main/Formula/idpbuilder.rb#L8

Solutions

A possible workaround could be to use the gorelease alternatives_names field: https://goreleaser.com/customization/homebrew/#versioned-formulas BUT this option is only available using gorelease PRO !!

I'm not even sure that gorelease could help us here as the formula file name must be created using a specific convention - https://docs.brew.sh/Versions to support different versions.

See dapr project as example: https://github.com/dapr/homebrew-tap

dapr-cli
...
dapr-cli@1.14.0-rc.1.rb
dapr-cli@1.14.0-rc.2.rb
dapr-cli@1.14.0-rc.3.rb
dapr-cli@1.14.0-rc.4.rb
dapr-cli@1.14.0-rc.5.rb
dapr-cli@1.14.0-rc.6.rb
dapr-cli@1.14.0-rc.7.rb
dapr-cli@1.14.0-rc.8.rb
dapr-cli@1.15.0-rc.2.rb
dapr-cli@1.15.0-rc.3.rb
dapr-cli@1.15.0-rc.4.rb
dapr-cli@1.15.0-rc.5.rb
dapr-cli@1.15.0-rc.6.rb

In this case, scripts should be used to populate the formula file in a normal releasing flow: https://github.com/dapr/homebrew-tap/blob/master/.github/workflows/release.yml

Here is another way to achieve that: https://github.com/knative/homebrew-client/blob/main/.github/workflows/knative-update-release.yaml#L21

Discussion

Independently of this issue that we should address, it is also important to figure out how users will consume the formula versions.

Personally, I think that we should do this:

• The idpbuilder.rb file should always include the tarball urls of the latest idpbuilder version released which is currently: 0.9.0
• When a new release is out, then we generate a new idpbuilder.rb file and create an old file packaging the previous release. Example, if we release 0.10.0, then we will generate a file idpbuilder@0.9.0.rb where the classname is equal to idpbuilderAT090, version: 0.9.0 etc with urls of that release AND idpbuilder.rb will include the version 0.10.0 and urls of the corresponding tarballs
• What about the nightly builds (aka release candidates). When a new RC (or nightly build is generated) on github, then a a corresponding formula file should be created idpbuilder@0.10.0-nightly-20250317 and classname: idpbuilderAT0100nightly20250317 and pushed.
  Remark: The users will not be able to install them directly (as brew installs by default what idpbuilder.rb contains) except if they update their homebrew/tap repo locally and use the command: brew install idpbuilder@0.10.0-nightly-20250317. TO BE VERIFIED

[cmoulliard]

Here is project's example with the different formulae: https://github.com/ch007m/homebrew-idp?tab=readme-ov-file#how-do-i-install-these-formulae

I create a patch for the missing formula to install the release 0.9.0 using brew install cnoe-io/tap/idpbuilder@0.9.0
cnoe-io/homebrew-tap#3

@nabuskey @punkwalker

[cmoulliard]

Here is an example of a bash that I tested locally to generate a nightly brew formula OR when a new release is out

#! /usr/bin/env bash

# Copyright 2024 The cnoe-io idpbuilder Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

set -o errexit
set -o nounset
set -o pipefail

VERSION_TO_TEST=${1:-}

# Retrieve version from given Idpbuilder repository tags
function get_latest_release_version() {
    local org_name="$1"
    local repo_name="$2"
    local version
    version="$(git ls-remote --tags --ref https://github.com/"${org_name}"/"${repo_name}".git \
      | cut -f2 \
      | cut -d 'v' -f2 \
      | sed 's#refs/tags/##' \
      | sort -Vr \
      | head -n 1)"
    echo "${version}"
}

# Return the major version of a release.
# For example, "v0.2.1" returns "0"
# Parameters: $1 - release version label.
function major_version() {
  local release="${1//v/}"
  local tokens=(${release//\./ })
  echo "${tokens[0]}"
}

# Return the minor version of a release.
# For example, "v0.2.1" returns "2"
# Parameters: $1 - release version label.
function minor_version() {
  local tokens=(${1//\./ })
  echo "${tokens[1]}"
}

# Return the release build number of a release.
# For example, "v0.2.1" returns "1".
# Parameters: $1 - release version label.
function patch_version() {
  local tokens=(${1//\./ })
  echo "${tokens[2]}"
}

# Generate file based on the inlined HEREDOC template.
function generate_tap_file() {
  local out=$1
  local version=$2
  local old_formula=${3:-""}
  local darwin_amd64_checksum darwin_arm64_checksum linux_amd64_checksum linux_arm64_checksum

  # Fetch checksum file from release and parse values
  checksums=$(mktemp)
  curl -fsSL "https://github.com/cnoe-io/idpbuilder/releases/download/v${2}/checksums.txt" > "$checksums"
  darwin_amd64_checksum=$(awk '$2=="idpbuilder-darwin-amd64"{print $1}' "$checksums")
  darwin_arm64_checksum=$(awk '$2=="idpbuilder-darwin-arm64"{print $1}' "$checksums")
  linux_amd64_checksum=$(awk '$2=="idpbuilder-linux-amd64"{print $1}' "$checksums")
  linux_arm64_checksum=$(awk '$2=="idpbuilder-linux-arm64"{print $1}' "$checksums")
  # Cleanup temp file
  rm "${checksums}"

cat <<EOF > "$out"
# Generated through hack/update-taps.sh. Don't edit manually.
# Next line is used to identify version of the file.
# idpbuilder_version:${version}
#
require "fileutils"

class ${old_formula} < Formula
  homepage "https://github.com/cnoe-io/idpbuilder"

  v = "v${version}"
  version v

  if OS.mac? && Hardware::CPU.intel?
    url "https://github.com/cnoe-io/idpbuilder/releases/download/#{v}/idpbuilder-darwin-amd64"
    sha256 "${darwin_amd64_checksum}"
  elsif OS.mac? && Hardware::CPU.arm?
    url "https://github.com/cnoe-io/idpbuilder/releases/download/#{v}/idpbuilder-darwin-arm64"
    sha256 "${darwin_arm64_checksum}"
  elsif OS.linux? && Hardware::CPU.arm?
    url "https://github.com/cnoe-io/idpbuilder/releases/download/#{v}/idpbuilder-linux-arm64"
    sha256 "${linux_arm64_checksum}"
  else
    url "https://github.com/cnoe-io/idpbuilder/releases/download/#{v}/idpbuilder-linux-amd64"
    sha256 "${linux_amd64_checksum}"
  end

  def install
    FileUtils.mv("idpbuilder", "idp")
    bin.install "idp"
  end

  test do
    system "#{bin}/idp --version"
  end
end
EOF
}

function generateNightlyFormulaClassname() {
  local version=$1
  echo "${version}" | grep "\-nightly" > /dev/null && echo "${version}" | sed -e 's/[\.\-]//g' | sed -e 's/n/N/' | xargs -I {} echo "IdpAT{}" || echo "Idp"
}

function generateFormulaClassname() {
    local version=$1
    echo "${version}" | sed -e 's/[\.\-]//g' | xargs -I {} echo "IdpAT{}"
}
# The script is meant to be executed though GH action to generate content update and review in the PR.

[[ ! -v REPO_ROOT_DIR ]] && REPO_ROOT_DIR="$(git rev-parse --show-toplevel)"
readonly REPO_ROOT_DIR

pushd $REPO_ROOT_DIR/Formula

if [[ -z ${VERSION_TO_TEST} ]]; then
  # Get latest released version from cnoe-io/idpbuilder git repository
  LATEST_IDP_VERSION=$(get_latest_release_version "cnoe-io" "idpbuilder")
else
  LATEST_IDP_VERSION=${VERSION_TO_TEST}
fi

#
# If this a nightly release, simply generate a new Formula file
# Remark: The Classname should be generated from the version as such:
#
# '@' replaced with 'AT'
# Dots '.' en dashes '-' removed
# First letter of a word uppercases
#
# File name:  idp@0.10.0-nightly.20250317.rb
# Class name: IdpAT0100Nightly20250317
#
if [[ ${LATEST_IDP_VERSION} == *"nightly"* ]]; then
  nightly_formula_filename="idp@${LATEST_IDP_VERSION}.rb"
  generate_tap_file "${nightly_formula_filename}" "${LATEST_IDP_VERSION}" "$(generateNightlyFormulaClassname ${LATEST_IDP_VERSION})"
  exit 0
fi

# Get sem version from idpbuilder.rb file, in format x.y.z
current_homebrew_version=$(cat "idp.rb" | grep "idpbuilder_version:" | cut -d ':' -f2)

echo "Generate the formula file for the old release: idp@${current_homebrew_version}.rb"
old_formula_filename="idp@${current_homebrew_version}.rb"
generate_tap_file "${old_formula_filename}" "${current_homebrew_version}" "$(generateFormulaClassname ${current_homebrew_version})"

echo "--------------------------------------"
echo "Generate the formula file idp.rb for the new release: ${LATEST_IDP_VERSION}"
generate_tap_file "idp.rb" "${LATEST_IDP_VERSION}" "$(generateFormulaClassname ${LATEST_IDP_VERSION})"

[cmoulliard]

Remark: The advantage of having several formulae, one / release is to avoid that users do this to install an older release.
We could, of course, continue to have one formula pointing to the latest official/supported release but then we will have to document the following brew trick AND it will not be possible to install nightly builds !

This is an example based on podman but the commands to be executed will be the same for idpbuilder !

❯ brew tap-new ch007m/podman
❯ brew extract --version='5.3.2' podman ch007m/homebrew-podman

AND

brew install ch007m/podman/podman@5.3.2