clusterversion: reword latest/min supported versions in Handle

Rename "binary version" to "latest version" and "binary min supported
version" to "min supported version" in `clusterversion.Handle` and
related code.

Informs: cockroachdb#112629
Release note: None

docs/tech-notes/version_upgrades.md

@@ -44,7 +44,7 @@ the specific fields should not be considered too much. They do
 not relate directly to the executable version!
 
 Instead, each `cockroach` executable has a range of supported
-cluster versions (in the code: `minBinaryVersion` ... `binaryVersion`).
+cluster versions (in the code: `minBinaryVersion` ... `latestVersion`).
 If a `cockroach` command observes a cluster version earlier than its
 minimum supported version, or later than its maximum supported
 version, it terminates.

pkg/ccl/backupccl/backup_test.go

@@ -8454,7 +8454,7 @@ func TestRestoringAcrossVersions(t *testing.T) {
 		// Bump the version down to outside our MinBinarySupportedVersion, and write
 		// it back out. This makes it ineligible for restore because of our restore
 		// version policy.
-		minSupportedVersion := tc.ApplicationLayer(0).ClusterSettings().Version.BinaryMinSupportedVersion()
+		minSupportedVersion := tc.ApplicationLayer(0).ClusterSettings().Version.MinSupportedVersion()
 		minSupportedVersion.Major -= 1
 		setManifestClusterVersion(minSupportedVersion)
 
@@ -8468,7 +8468,7 @@ func TestRestoringAcrossVersions(t *testing.T) {
 		// Bump the version down to the min supported binary version, and write it
 		// back out. This makes it eligible for restore because of our restore
 		// version policy.
-		minBinaryVersion := tc.ApplicationLayer(0).ClusterSettings().Version.BinaryMinSupportedVersion()
+		minBinaryVersion := tc.ApplicationLayer(0).ClusterSettings().Version.MinSupportedVersion()
 		setManifestClusterVersion(minBinaryVersion)
 		sqlDB.Exec(t, `RESTORE DATABASE r1 FROM 'nodelocal://1/cross_version'`)
 		sqlDB.Exec(t, `DROP DATABASE r1`)

pkg/ccl/backupccl/restore_job.go

@@ -1937,7 +1937,7 @@ func (r *restoreResumer) validateJobIsResumable(execConfig *sql.ExecutorConfig)
 	// the CreationClusterVersion may still be equal to binaryVersion,
 	// which means the cluster restore will proceed.
 	creationClusterVersion := r.job.Payload().CreationClusterVersion
-	binaryVersion := execConfig.Settings.Version.BinaryVersion()
+	binaryVersion := execConfig.Settings.Version.LatestVersion()
 	isClusterRestore := details.DescriptorCoverage == tree.AllDescriptors
 	if isClusterRestore && creationClusterVersion.Less(binaryVersion) {
 		return clusterRestoreDuringUpgradeErr(creationClusterVersion, binaryVersion)

pkg/ccl/backupccl/restore_mid_schema_change_test.go

@@ -231,10 +231,10 @@ func restoreMidSchemaChange(
 		// option to ensure the restore is successful on development branches. This
 		// is because, while the backups were generated on release branches and have
 		// versions such as 22.2 in their manifest, the development branch will have
-		// a BinaryMinSupportedVersion offset by the clusterversion.DevOffset
+		// a MinSupportedVersion offset by the clusterversion.DevOffset
 		// described in `pkg/clusterversion/cockroach_versions.go`. This will mean
 		// that the manifest version is always less than the
-		// BinaryMinSupportedVersion which will in turn fail the restore unless we
+		// MinSupportedVersion which will in turn fail the restore unless we
 		// pass in the specified option to elide the compatability check.
 		restoreQuery := "RESTORE defaultdb.* FROM LATEST IN $1 WITH UNSAFE_RESTORE_INCOMPATIBLE_VERSION"
 		if isClusterRestore {

pkg/ccl/backupccl/restore_old_sequences_test.go

@@ -83,10 +83,10 @@ func restoreOldSequencesTest(exportDir string, isSchemaOnly bool) func(t *testin
 		// option to ensure the restore is successful on development branches. This
 		// is because, while the backups were generated on release branches and have
 		// versions such as 22.2 in their manifest, the development branch will have
-		// a BinaryMinSupportedVersion offset by the clusterversion.DevOffset
+		// a MinSupportedVersion offset by the clusterversion.DevOffset
 		// described in `pkg/clusterversion/cockroach_versions.go`. This will mean
 		// that the manifest version is always less than the
-		// BinaryMinSupportedVersion which will in turn fail the restore unless we
+		// MinSupportedVersion which will in turn fail the restore unless we
 		// pass in the specified option to elide the compatability check.
 		restoreQuery := `RESTORE test.* FROM LATEST IN $1 WITH UNSAFE_RESTORE_INCOMPATIBLE_VERSION`
 		if isSchemaOnly {

pkg/ccl/backupccl/restore_old_versions_test.go

@@ -162,10 +162,10 @@ func restoreOldVersionClusterTest(exportDir string) func(t *testing.T) {
 		// option to ensure the restore is successful on development branches. This
 		// is because, while the backups were generated on release branches and have
 		// versions such as 22.2 in their manifest, the development branch will have
-		// a BinaryMinSupportedVersion offset by the clusterversion.DevOffset
+		// a MinSupportedVersion offset by the clusterversion.DevOffset
 		// described in `pkg/clusterversion/cockroach_versions.go`. This will mean
 		// that the manifest version is always less than the
-		// BinaryMinSupportedVersion which will in turn fail the restore unless we
+		// MinSupportedVersion which will in turn fail the restore unless we
 		// pass in the specified option to elide the compatability check.
 		sqlDB.Exec(t, `RESTORE FROM LATEST IN $1 WITH UNSAFE_RESTORE_INCOMPATIBLE_VERSION`, localFoo)
 
@@ -332,10 +332,10 @@ func fullClusterRestoreSystemRoleMembersWithoutIDs(exportDir string) func(t *tes
 		// option to ensure the restore is successful on development branches. This
 		// is because, while the backups were generated on release branches and have
 		// versions such as 22.2 in their manifest, the development branch will have
-		// a BinaryMinSupportedVersion offset by the clusterversion.DevOffset
+		// a MinSupportedVersion offset by the clusterversion.DevOffset
 		// described in `pkg/clusterversion/cockroach_versions.go`. This will mean
 		// that the manifest version is always less than the
-		// BinaryMinSupportedVersion which will in turn fail the restore unless we
+		// MinSupportedVersion which will in turn fail the restore unless we
 		// pass in the specified option to elide the compatability check.
 		sqlDB.Exec(t, fmt.Sprintf("RESTORE FROM '%s' WITH UNSAFE_RESTORE_INCOMPATIBLE_VERSION", localFoo))
 
@@ -367,10 +367,10 @@ func fullClusterRestoreSystemPrivilegesWithoutIDs(exportDir string) func(t *test
 		// option to ensure the restore is successful on development branches. This
 		// is because, while the backups were generated on release branches and have
 		// versions such as 22.2 in their manifest, the development branch will have
-		// a BinaryMinSupportedVersion offset by the clusterversion.DevOffset
+		// a MinSupportedVersion offset by the clusterversion.DevOffset
 		// described in `pkg/clusterversion/cockroach_versions.go`. This will mean
 		// that the manifest version is always less than the
-		// BinaryMinSupportedVersion which will in turn fail the restore unless we
+		// MinSupportedVersion which will in turn fail the restore unless we
 		// pass in the specified option to elide the compatability check.
 		sqlDB.Exec(t, fmt.Sprintf("RESTORE FROM '%s' WITH UNSAFE_RESTORE_INCOMPATIBLE_VERSION", localFoo))
 
@@ -402,10 +402,10 @@ func fullClusterRestoreSystemDatabaseRoleSettingsWithoutIDs(exportDir string) fu
 		// option to ensure the restore is successful on development branches. This
 		// is because, while the backups were generated on release branches and have
 		// versions such as 22.2 in their manifest, the development branch will have
-		// a BinaryMinSupportedVersion offset by the clusterversion.DevOffset
+		// a MinSupportedVersion offset by the clusterversion.DevOffset
 		// described in `pkg/clusterversion/cockroach_versions.go`. This will mean
 		// that the manifest version is always less than the
-		// BinaryMinSupportedVersion which will in turn fail the restore unless we
+		// MinSupportedVersion which will in turn fail the restore unless we
 		// pass in the specified option to elide the compatability check.
 		sqlDB.Exec(t, fmt.Sprintf("RESTORE FROM '%s' WITH UNSAFE_RESTORE_INCOMPATIBLE_VERSION", localFoo))
 
@@ -437,10 +437,10 @@ func fullClusterRestoreSystemExternalConnectionsWithoutIDs(exportDir string) fun
 		// option to ensure the restore is successful on development branches. This
 		// is because, while the backups were generated on release branches and have
 		// versions such as 22.2 in their manifest, the development branch will have
-		// a BinaryMinSupportedVersion offset by the clusterversion.DevOffset
+		// a MinSupportedVersion offset by the clusterversion.DevOffset
 		// described in `pkg/clusterversion/cockroach_versions.go`. This will mean
 		// that the manifest version is always less than the
-		// BinaryMinSupportedVersion which will in turn fail the restore unless we
+		// MinSupportedVersion which will in turn fail the restore unless we
 		// pass in the specified option to elide the compatability check.
 		sqlDB.Exec(t, fmt.Sprintf("RESTORE FROM '%s' WITH UNSAFE_RESTORE_INCOMPATIBLE_VERSION", localFoo))
 

pkg/ccl/backupccl/restore_planning.go

@@ -1646,7 +1646,7 @@ func checkBackupManifestVersionCompatability(
 
 	// We support restoring a backup that was taken on a cluster with a cluster
 	// version >= the earliest binary version that we can interoperate with.
-	minimumRestoreableVersion := version.BinaryMinSupportedVersion()
+	minimumRestoreableVersion := version.MinSupportedVersion()
 	currentActiveVersion := version.ActiveVersion(ctx)
 
 	for i := range mainBackupManifests {
@@ -1869,7 +1869,7 @@ func doRestorePlan(
 		// Validate that we aren't in the middle of an upgrade. To avoid unforseen
 		// issues, we want to avoid full cluster restores if it is possible that an
 		// upgrade is in progress. We also check this during Resume.
-		binaryVersion := p.ExecCfg().Settings.Version.BinaryVersion()
+		binaryVersion := p.ExecCfg().Settings.Version.LatestVersion()
 		clusterVersion := p.ExecCfg().Settings.Version.ActiveVersion(ctx).Version
 		if clusterVersion.Less(binaryVersion) {
 			return clusterRestoreDuringUpgradeErr(clusterVersion, binaryVersion)

pkg/ccl/kvccl/kvtenantccl/upgradeccl/tenant_upgrade_test.go

@@ -271,7 +271,7 @@ func TestTenantUpgrade(t *testing.T) {
 		v1,
 		false, // initializeVersion
 	)
-	// Initialize the version to the BinaryMinSupportedVersion.
+	// Initialize the version to the MinSupportedVersion.
 	require.NoError(t, clusterversion.Initialize(ctx,
 		clusterversion.TestingBinaryMinSupportedVersion, &settings.SV))
 
@@ -429,7 +429,7 @@ func TestTenantUpgradeFailure(t *testing.T) {
 		v0,
 		false, // initializeVersion
 	)
-	// Initialize the version to the BinaryMinSupportedVersion.
+	// Initialize the version to the MinSupportedVersion.
 	ts := serverutils.StartServerOnly(t, base.TestServerArgs{
 		DefaultTestTenant: base.TestControlsTenantsExplicitly,
 		Settings:          settings,

pkg/ccl/kvccl/kvtenantccl/upgradeinterlockccl/local_test_util_test.go

@@ -118,7 +118,7 @@ func runTest(t *testing.T, variant sharedtestutil.TestVariant, test sharedtestut
 		slinstance.DefaultHeartBeat.Override(ctx, &s.SV, heartbeatOverride)
 	}
 
-	// Initialize the version to the BinaryMinSupportedVersion so that
+	// Initialize the version to the MinSupportedVersion so that
 	// we can perform upgrades.
 	settings := cluster.MakeTestingClusterSettingsWithVersions(bv, msv, false /* initializeVersion */)
 	disableBackgroundTasks(settings)

pkg/clusterversion/clusterversion.go

@@ -8,11 +8,11 @@
 // by the Apache License, Version 2.0, included in the file
 // licenses/APL.txt.
 
-// Package clusterversion defines the interfaces to interact with cluster/binary
-// versions in order accommodate backward incompatible behaviors. It handles the
-// feature gates and so must maintain a fairly lightweight set of dependencies.
-// The upgrade sub-package handles advancing a cluster from one version to
-// a later one.
+// Package clusterversion defines the interfaces to interact with cluster
+// versions in order to accommodate backward incompatible behaviors. It handles
+// the feature gates and so must maintain a fairly lightweight set of
+// dependencies. The upgrade sub-package handles advancing a cluster from one
+// version to a later one.
 //
 // Ideally, every code change in a database would be backward compatible, but
 // this is not always possible. Some features, fixes, or cleanups need to
@@ -21,15 +21,16 @@
 // disruption. It works as follows:
 //
 //   - Each node in the cluster is running a binary that was released at some
-//     version ("binary version"). We allow for rolling upgrades, so two nodes in
-//     the cluster may be running different binary versions. All nodes in a given
-//     cluster must be within 1 major release of each other (i.e. to upgrade two
-//     major releases, the cluster must first be rolled onto X+1 and then to X+2).
+//     version which corresponds to a certain logical cluster version ("latest
+//     version"). We allow for rolling upgrades, so two nodes in the cluster may
+//     be running different binary versions. All nodes in a given cluster must
+//     be within 1 major release of each other (i.e. to upgrade two major
+//     releases, the cluster must first be rolled onto X+1 and then to X+2).
 //   - Separate from the build versions of the binaries, the cluster itself has a
-//     logical "active cluster version", the version all the binaries are
-//     currently operating at. This is used for two related things: first as a
-//     promise from the user that they'll never downgrade any nodes in the cluster
-//     to a binary below some "minimum supported version", and second, to unlock
+//     logical "active cluster version", the version all nodes are currently
+//     operating at. This is used for two related things: first as a promise
+//     from the user that they'll never downgrade any nodes in the cluster to a
+//     binary below some "minimum supported version", and second, to unlock
 //     features that are not backwards compatible (which is now safe given that
 //     the old binary will never be used).
 //   - Each binary can operate within a "range of supported versions". When a
@@ -108,12 +109,12 @@ type Handle interface {
 	// node has, and it will too, eventually.
 	IsActive(context.Context, Key) bool
 
-	// BinaryVersion returns the build version of this binary.
-	BinaryVersion() roachpb.Version
+	// LatestVersion returns the latest cluster version understood by this binary.
+	LatestVersion() roachpb.Version
 
-	// BinaryMinSupportedVersion returns the earliest binary version that can
+	// MinSupportedVersion returns the earliest cluster version that can
 	// interoperate with this binary.
-	BinaryMinSupportedVersion() roachpb.Version
+	MinSupportedVersion() roachpb.Version
 
 	// SetActiveVersion lets the caller set the given cluster version as the
 	// currently active one. When a new active version is set, all subsequent
@@ -148,28 +149,27 @@ type Handle interface {
 
 // handleImpl is a concrete implementation of Handle. It mostly relegates to the
 // underlying cluster version setting, though provides a way for callers to
-// override the binary and minimum supported versions (for tests usually).
+// override the latest and minimum supported versions (for tests usually).
 type handleImpl struct {
 	// setting is the version that this handle operates on.
 	setting *clusterVersionSetting
 	// sv captures the mutable state associated with usage of the otherwise
 	// immutable cluster version setting.
 	sv *settings.Values
 
-	// Each handler stores its own view of the binary and minimum supported
-	// version. Tests can use `MakeVersionHandleWithOverride` to specify
-	// versions other than the baked in ones, but by default
-	// (`MakeVersionHandle`) they are initialized with this binary's build
-	// and minimum supported versions.
-	binaryVersion             roachpb.Version
-	binaryMinSupportedVersion roachpb.Version
+	// Each handler stores its own view of the latest and minimum supported
+	// version. Tests can use `MakeVersionHandleWithOverride` to specify versions
+	// other than the baked in ones, but by default (`MakeVersionHandle`) they are
+	// initialized with this binary's latest and minimum supported versions.
+	latestVersion       roachpb.Version
+	minSupportedVersion roachpb.Version
 }
 
 var _ Handle = (*handleImpl)(nil)
 
-// MakeVersionHandle returns a Handle that has its binary and minimum
-// supported versions initialized to this binary's build and it's minimum
-// supported versions respectively.
+// MakeVersionHandle returns a Handle that has its latest and minimum supported
+// versions initialized to this binary's build and its minimum supported
+// versions respectively.
 func MakeVersionHandle(sv *settings.Values) Handle {
 	return MakeVersionHandleWithOverride(sv, Latest.Version(), MinSupported.Version())
 }
@@ -180,21 +180,21 @@ func MakeVersionHandle(sv *settings.Values) Handle {
 // It's typically used in tests that want to override the default binary and
 // minimum supported versions.
 func MakeVersionHandleWithOverride(
-	sv *settings.Values, binaryVersion, binaryMinSupportedVersion roachpb.Version,
+	sv *settings.Values, latestVersion, minSupportedVersion roachpb.Version,
 ) Handle {
-	return newHandleImpl(version, sv, binaryVersion, binaryMinSupportedVersion)
+	return newHandleImpl(version, sv, latestVersion, minSupportedVersion)
 }
 
 func newHandleImpl(
 	setting *clusterVersionSetting,
 	sv *settings.Values,
-	binaryVersion, binaryMinSupportedVersion roachpb.Version,
+	latestVersion, minSupportedVersion roachpb.Version,
 ) Handle {
 	return &handleImpl{
-		setting:                   setting,
-		sv:                        sv,
-		binaryVersion:             binaryVersion,
-		binaryMinSupportedVersion: binaryMinSupportedVersion,
+		setting:             setting,
+		sv:                  sv,
+		latestVersion:       latestVersion,
+		minSupportedVersion: minSupportedVersion,
 	}
 }
 
@@ -240,14 +240,14 @@ func (v *handleImpl) IsActive(ctx context.Context, key Key) bool {
 	return v.setting.isActive(ctx, v.sv, key)
 }
 
-// BinaryVersion implements the Handle interface.
-func (v *handleImpl) BinaryVersion() roachpb.Version {
-	return v.binaryVersion
+// LatestVersion is part of the Handle interface.
+func (v *handleImpl) LatestVersion() roachpb.Version {
+	return v.latestVersion
 }
 
-// BinaryMinSupportedVersion implements the Handle interface.
-func (v *handleImpl) BinaryMinSupportedVersion() roachpb.Version {
-	return v.binaryMinSupportedVersion
+// MinSupportedVersion is part of the Handle interface.
+func (v *handleImpl) MinSupportedVersion() roachpb.Version {
+	return v.minSupportedVersion
 }
 
 // IsActiveVersion returns true if the features of the supplied version are