Support custom version reference files (#1002)

* Parse module version ref from config

* Use version refs in prerelease

* Add a changelog entry

* Test errors from updateVersionGoFile

* Apply suggestions from code review

Co-authored-by: Robert Pająk <[email protected]>

* Add modules sect. to versions-example

---------

Co-authored-by: Robert Pająk <[email protected]>

Author: MrAlias

.chloggen/version-refs.yaml

@@ -0,0 +1,20 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. crosslink)
+component: multimod
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Support custom version reference files
+
+# One or more tracking issues related to the change
+issues: [994]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  A new "modules" section is parsed in the version configuration. This section
+  defines relative file paths for files that references the version of the
+  module set. If this section is not used for a module the default "version.go"
+  file at the root of the module directory is still assumed.

multimod/docs/versions-example.yaml

@@ -58,4 +58,9 @@ module-sets:
     modules:
       - go.opentelemetry.io/otel/oteltest
 excluded-modules:
-  - go.opentelemetry.io/otel/internal/tools
+  - go.opentelemetry.io/otel/internal/tools
+modules:
+  go.opentelemetry.io/otel:
+    version-refs:
+      - ./versions.go
+      - ./internal/distro/distro.go

multimod/internal/prerelease/prerelease.go

@@ -149,54 +149,57 @@ func (p prerelease) checkModuleSetUpToDate(repo *git.Repository) (bool, error) {
 // updateAllVersionGo updates the version.go file containing a hardcoded semver version string
 // for modules within a set, if the file exists.
 func (p prerelease) updateAllVersionGo() error {
+	var err error
 	for _, modPath := range p.ModSetPaths() {
 		modFilePath := p.ModPathMap[modPath]
+		root := filepath.Dir(string(modFilePath))
 
-		versionGoDir := filepath.Dir(string(modFilePath))
-		versionGoFilePath := filepath.Join(versionGoDir, "version.go")
-
-		// check if version.go file exists
-		_, err := os.Stat(versionGoFilePath)
-		if err != nil {
-			if os.IsNotExist(err) {
-				continue
-			}
-			return fmt.Errorf("could not check existence of %v: %w", versionGoFilePath, err)
-		}
-		if err = updateVersionGoFile(versionGoFilePath, p.ModSetVersion()); err != nil {
-			return fmt.Errorf("could not update %v: %w", versionGoFilePath, err)
+		vRefs := p.ModInfoMap[modPath].VersionRefs(root)
+		if len(vRefs) == 0 {
+			vRefs = defaultFileRefs(root)
 		}
 
+		for _, vRef := range vRefs {
+			e := updateVersionGoFile(vRef, p.ModSetVersion())
+			err = errors.Join(err, e)
+		}
 	}
-	return nil
+	return err
 }
 
-// updateVersionGoFile updates one version.go file.
-// TODO: a potential improvement is to use an AST package rather than regex to perform replacement.
-func updateVersionGoFile(filePath string, newVersion string) error {
-	if !strings.HasSuffix(filePath, "version.go") {
-		return errors.New("cannot update file passed that does not end with version.go")
-	}
-	log.Printf("... Updating file %v\n", filePath)
-
-	newVersionGoFile, err := os.ReadFile(filepath.Clean(filePath))
+func defaultFileRefs(root string) []string {
+	path := filepath.Join(root, "version.go")
+	_, err := os.Stat(path)
 	if err != nil {
-		panic(err)
+		if !os.IsNotExist(err) {
+			log.Printf("Warning: could not check existence of %v: %v\n", path, err)
+		}
+		// The file does not exist, or we cannot check its existence.
+		return nil
 	}
+	return []string{path}
+}
 
-	oldVersionRegex := shared.SemverRegexNumberOnly
-	r, err := regexp.Compile(oldVersionRegex)
+var verRegex = regexp.MustCompile(shared.SemverRegexNumberOnly)
+
+// updateVersionGoFile updates all versions within the file at path to use the
+// new version number ver.
+func updateVersionGoFile(path string, ver string) error {
+	// TODO: There is a potential improvement is to use an AST package rather than regex
+	// to perform replacement.
+	log.Printf("... Updating version references in %s to %s\n", path, ver)
+
+	data, err := os.ReadFile(filepath.Clean(path))
 	if err != nil {
-		return fmt.Errorf("error compiling regex: %w", err)
+		return fmt.Errorf("error reading version.go file %v: %w", path, err)
 	}
 
-	newVersionNumberOnly := strings.TrimPrefix(newVersion, "v")
-
-	newVersionGoFile = r.ReplaceAll(newVersionGoFile, []byte(newVersionNumberOnly))
+	v := strings.TrimPrefix(ver, "v")
+	data = verRegex.ReplaceAll(data, []byte(v))
 
-	// overwrite the version.go file
-	if err := os.WriteFile(filePath, newVersionGoFile, 0600); err != nil {
-		return fmt.Errorf("error overwriting go.mod file: %w", err)
+	// Overwrite filePath.
+	if err := os.WriteFile(path, data, 0600); err != nil {
+		return fmt.Errorf("error overwriting %s file: %w", path, err)
 	}
 
 	return nil

multimod/internal/prerelease/prerelease_test.go

@@ -198,6 +198,11 @@ func TestUpdateAllVersionGo(t *testing.T) {
 			"func Version() string {\n\t" +
 			"return \"1.0.0-OLD\"\n" +
 			"}\n"),
+		filepath.Join(tmpRootDir, "test", "test1", "internal", "version", "distro.go"): []byte("package version\"\n\n" +
+			"// Version is the current release version of OpenTelemetry in use.\n" +
+			"func Version() string {\n\t" +
+			"return \"1.0.0-OLD\"\n" +
+			"}\n"),
 		filepath.Join(tmpRootDir, "test", "version.go"): []byte("package test2 // import \"go.opentelemetry.io/test/test2\"\n\n" +
 			"// version is the current release version of OpenTelemetry in use.\n" +
 			"func version() string {\n\t" +
@@ -219,6 +224,11 @@ func TestUpdateAllVersionGo(t *testing.T) {
 					"func Version() string {\n\t" +
 					"return \"1.2.3-RC1+meta\"\n" +
 					"}\n"),
+				filepath.Join(tmpRootDir, "test", "test1", "internal", "version", "distro.go"): []byte("package version\"\n\n" +
+					"// Version is the current release version of OpenTelemetry in use.\n" +
+					"func Version() string {\n\t" +
+					"return \"1.2.3-RC1+meta\"\n" +
+					"}\n"),
 				filepath.Join(tmpRootDir, "test", "version.go"): []byte("package test2 // import \"go.opentelemetry.io/test/test2\"\n\n" +
 					"// version is the current release version of OpenTelemetry in use.\n" +
 					"func version() string {\n\t" +
@@ -235,6 +245,11 @@ func TestUpdateAllVersionGo(t *testing.T) {
 					"func Version() string {\n\t" +
 					"return \"1.0.0-OLD\"\n" +
 					"}\n"),
+				filepath.Join(tmpRootDir, "test", "test1", "internal", "version", "distro.go"): []byte("package version\"\n\n" +
+					"// Version is the current release version of OpenTelemetry in use.\n" +
+					"func Version() string {\n\t" +
+					"return \"1.0.0-OLD\"\n" +
+					"}\n"),
 				filepath.Join(tmpRootDir, "test", "version.go"): []byte("package test2 // import \"go.opentelemetry.io/test/test2\"\n\n" +
 					"// version is the current release version of OpenTelemetry in use.\n" +
 					"func version() string {\n\t" +
@@ -251,6 +266,11 @@ func TestUpdateAllVersionGo(t *testing.T) {
 					"func Version() string {\n\t" +
 					"return \"1.0.0-OLD\"\n" +
 					"}\n"),
+				filepath.Join(tmpRootDir, "test", "test1", "internal", "version", "distro.go"): []byte("package version\"\n\n" +
+					"// Version is the current release version of OpenTelemetry in use.\n" +
+					"func Version() string {\n\t" +
+					"return \"1.0.0-OLD\"\n" +
+					"}\n"),
 				filepath.Join(tmpRootDir, "test", "version.go"): []byte("package test2 // import \"go.opentelemetry.io/test/test2\"\n\n" +
 					"// version is the current release version of OpenTelemetry in use.\n" +
 					"func version() string {\n\t" +
@@ -612,3 +632,22 @@ func TestUpdateAll(t *testing.T) {
 		)
 	}
 }
+
+func TestUpdateVersionGoFileErrs(t *testing.T) {
+	t.Run("NotExist", func(t *testing.T) {
+		path := filepath.Join(t.TempDir(), "version.go")
+		err := updateVersionGoFile(path, "")
+		assert.ErrorIs(t, err, os.ErrNotExist, "version.go does not exist")
+	})
+	t.Run("ReadOnly", func(t *testing.T) {
+		path := filepath.Join(t.TempDir(), "version.go")
+
+		const readOnlyPerm = 0444
+		file, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY, readOnlyPerm) // nolint:gosec  // Var filepath okay in test.
+		require.NoError(t, err)
+		require.NoError(t, file.Close())
+
+		err = updateVersionGoFile(path, "")
+		assert.ErrorIs(t, err, os.ErrPermission, "write error not embedded")
+	})
+}

multimod/internal/prerelease/test_data/update_all_version_go/versions_valid.yaml

@@ -27,3 +27,8 @@ module-sets:
       - go.opentelemetry.io/testroot/v2
 excluded-modules:
   - go.opentelemetry.io/test/testexcluded
+modules:
+  go.opentelemetry.io/test/test1:
+    version-refs:
+      - ./version.go
+      - ./internal/version/distro.go

multimod/internal/shared/test_data/alt_version_files/versions.yaml

@@ -0,0 +1,40 @@
+# Copyright The OpenTelemetry 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.
+
+module-sets:
+  mod-set-1:
+    version: v0.0.1
+    modules:
+      - go.opentelemetry.io/test/test1
+      - go.opentelemetry.io/test/test2
+  mod-set-2:
+    version: v0.1.0
+    modules:
+      - go.opentelemetry.io/test3
+excluded-modules:
+  - go.opentelemetry.io/excluded1
+modules:
+  go.opentelemetry.io/test/test1:
+    version-refs:
+      - ./versions.go
+      - ./internal/version/versions.go
+  go.opentelemetry.io/test/test2:
+    version-refs:
+      - ./internal/deeper/version/versions.go
+  go.opentelemetry.io/excluded1:
+    version-refs:
+      - ./sub/pkg/version/versions.go
+  go.opentelemetry.io/unknown:
+    version-refs:
+      - ../unknown/versions.go

multimod/internal/shared/versions.go

@@ -16,6 +16,7 @@ package shared
 
 import (
 	"fmt"
+	"path/filepath"
 
 	"github.com/spf13/viper"
 )
@@ -29,8 +30,9 @@ const (
 
 // versionConfig is needed to parse the versions.yaml file with viper.
 type versionConfig struct {
-	ModuleSets      ModuleSetMap `mapstructure:"module-sets"`
-	ExcludedModules []ModulePath `mapstructure:"excluded-modules"`
+	ModuleSets      ModuleSetMap             `mapstructure:"module-sets"`
+	ExcludedModules []ModulePath             `mapstructure:"excluded-modules"`
+	Modules         map[ModulePath]ModuleDef `mapstructure:"modules"`
 	ignoreExcluded  bool
 }
 
@@ -56,6 +58,13 @@ type ModuleRef struct {
 	Version string
 }
 
+// ModuleDef are the definitions related to a module.
+type ModuleDef struct {
+	// VersionRefs are the files that contain the module version and need to be
+	// updated when the module version is updated.
+	VersionRefs []string `mapstructure:"version-refs"`
+}
+
 // ModuleInfoMap is a mapping from a module's import path to its ModuleInfo struct.
 type ModuleInfoMap map[ModulePath]ModuleInfo
 
@@ -64,6 +73,21 @@ type ModuleInfoMap map[ModulePath]ModuleInfo
 type ModuleInfo struct {
 	ModuleSetName string
 	Version       string
+
+	versionRefs []string
+}
+
+// VersionRefs returns the path to all version references for the module. which
+// are the files that contain the module version and need to be updated when
+// the module version is updated.
+//
+// All paths are relative to the root path provided.
+func (mi ModuleInfo) VersionRefs(root string) []string {
+	out := make([]string, len(mi.versionRefs))
+	for i, ref := range mi.versionRefs {
+		out[i] = filepath.Join(root, ref)
+	}
+	return out
 }
 
 // ModuleFilePath holds the file path to the go.mod file within the repo,
@@ -80,22 +104,25 @@ type ModuleTagName string
 // readVersioningFile reads in a versioning file (typically given as versions.yaml) and returns
 // a versionConfig struct.
 func readVersioningFile(versioningFilename string) (versionConfig, error) {
-	viper.SetConfigFile(versioningFilename)
+	// Allow '.' in configuration keys.
+	// (i.e go.opentelemetry.io/otel is a valid key).
+	v := viper.NewWithOptions(viper.KeyDelimiter("\\"))
+	v.SetConfigFile(versioningFilename)
 
 	var versionCfg versionConfig
 
-	if err := viper.ReadInConfig(); err != nil {
+	if err := v.ReadInConfig(); err != nil {
 		return versionConfig{}, fmt.Errorf("error reading versionsConfig file: %w", err)
 	}
 
-	if err := viper.Unmarshal(&versionCfg); err != nil {
+	if err := v.Unmarshal(&versionCfg); err != nil {
 		return versionConfig{}, fmt.Errorf("unable to unmarshal versionsConfig: %w", err)
 	}
 
-	if viper.ConfigFileUsed() != versioningFilename {
+	if v.ConfigFileUsed() != versioningFilename {
 		return versionConfig{}, fmt.Errorf(
 			"config file used (%v) does not match input file (%v)",
-			viper.ConfigFileUsed(),
+			v.ConfigFileUsed(),
 			versioningFilename,
 		)
 	}
@@ -125,7 +152,11 @@ func (versionCfg versionConfig) buildModuleMap() (ModuleInfoMap, error) {
 			if versionCfg.shouldExcludeModule(modPath) {
 				return nil, fmt.Errorf("module %v is an excluded module and should not be versioned", modPath)
 			}
-			modMap[modPath] = ModuleInfo{setName, moduleSet.Version}
+			modMap[modPath] = ModuleInfo{
+				setName,
+				moduleSet.Version,
+				versionCfg.Modules[modPath].VersionRefs,
+			}
 		}
 	}
 

multimod/internal/shared/versions_test.go

@@ -352,3 +352,50 @@ func TestBuildModulePathMap(t *testing.T) {
 	require.NoError(t, err)
 	assert.Equal(t, expected, actual)
 }
+
+func TestAltVersionFiles(t *testing.T) {
+	vFile := filepath.Join(testDataDir, "alt_version_files/versions.yaml")
+	actual, err := readVersioningFile(vFile)
+	require.NoError(t, err)
+	assert.Equal(t, versionConfig{
+		ModuleSets: ModuleSetMap{
+			"mod-set-1": ModuleSet{
+				Version: "v0.0.1",
+				Modules: []ModulePath{
+					"go.opentelemetry.io/test/test1",
+					"go.opentelemetry.io/test/test2",
+				},
+			},
+			"mod-set-2": ModuleSet{
+				Version: "v0.1.0",
+				Modules: []ModulePath{
+					"go.opentelemetry.io/test3",
+				},
+			},
+		},
+		ExcludedModules: []ModulePath{"go.opentelemetry.io/excluded1"},
+		Modules: map[ModulePath]ModuleDef{
+			"go.opentelemetry.io/excluded1": {
+				VersionRefs: []string{
+					"./sub/pkg/version/versions.go",
+				},
+			},
+			"go.opentelemetry.io/test/test1": {
+				VersionRefs: []string{
+					"./versions.go",
+					"./internal/version/versions.go",
+				},
+			},
+			"go.opentelemetry.io/test/test2": {
+				VersionRefs: []string{
+					"./internal/deeper/version/versions.go",
+				},
+			},
+			"go.opentelemetry.io/unknown": {
+				VersionRefs: []string{
+					"../unknown/versions.go",
+				},
+			},
+		},
+	}, actual)
+}