Add versionHeightOffsetAppliesTo property to VersionOptions

Co-authored-by: AArnott <[email protected]>

Author: Copilot

src/NerdBank.GitVersioning/ReleaseManager.cs

@@ -282,8 +282,9 @@ private void UpdateVersion(LibGit2Context context, SemanticVersion oldVersion, S
         {
             if (versionOptions.VersionHeightOffset != -1 && versionOptions.VersionHeightPosition.HasValue && SemanticVersion.WillVersionChangeResetVersionHeight(versionOptions.Version, newVersion, versionOptions.VersionHeightPosition.Value))
             {
-                // The version will be reset by this change, so remove the version height offset property.
+                // The version will be reset by this change, so remove the version height offset properties.
                 versionOptions.VersionHeightOffset = null;
+                versionOptions.VersionHeightOffsetAppliesTo = null;
             }
 
             versionOptions.Version = newVersion;

src/NerdBank.GitVersioning/VersionOptions.cs

@@ -73,6 +73,12 @@ public class VersionOptions : IEquatable<VersionOptions>
     [DebuggerBrowsable(DebuggerBrowsableState.Never)]
     private int? buildNumberOffset;
 
+    /// <summary>
+    /// Backing field for the <see cref="VersionHeightOffsetAppliesTo"/> property.
+    /// </summary>
+    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
+    private SemanticVersion? versionHeightOffsetAppliesTo;
+
     /// <summary>
     /// Backing field for the <see cref="SemVer1NumericIdentifierPadding"/> property.
     /// </summary>
@@ -146,6 +152,7 @@ public VersionOptions(VersionOptions copyFrom)
         this.version = copyFrom.version;
         this.assemblyVersion = copyFrom.assemblyVersion is object ? new AssemblyVersionOptions(copyFrom.assemblyVersion) : null;
         this.buildNumberOffset = copyFrom.buildNumberOffset;
+        this.versionHeightOffsetAppliesTo = copyFrom.versionHeightOffsetAppliesTo;
         this.semVer1NumericIdentifierPadding = copyFrom.semVer1NumericIdentifierPadding;
         this.gitCommitIdShortFixedLength = copyFrom.gitCommitIdShortFixedLength;
         this.gitCommitIdShortAutoMinimum = copyFrom.gitCommitIdShortAutoMinimum;
@@ -368,6 +375,25 @@ public int VersionHeightOffsetOrDefault
 #pragma warning restore CS0618
     }
 
+    /// <summary>
+    /// Gets or sets the version to which the <see cref="VersionHeightOffset"/> applies.
+    /// When the <see cref="Version"/> property changes such that the version height would be reset,
+    /// and this property does not match the new version, the <see cref="VersionHeightOffset"/> will be ignored.
+    /// </summary>
+    /// <value>A semantic version, or <see langword="null"/> to indicate no constraint.</value>
+    /// <remarks>
+    /// This property is typically used in conjunction with <see cref="VersionHeightOffset"/> to ensure
+    /// that the offset is only applied when the version matches the expected version. When the version
+    /// changes such that the version height would reset, this property can be used to automatically
+    /// stop applying the offset without needing to manually remove it from all version.json files.
+    /// </remarks>
+    [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
+    public SemanticVersion? VersionHeightOffsetAppliesTo
+    {
+        get => this.versionHeightOffsetAppliesTo;
+        set => this.SetIfNotReadOnly(ref this.versionHeightOffsetAppliesTo, value);
+    }
+
     /// <summary>
     /// Gets or sets the minimum number of digits to use for numeric identifiers in SemVer 1.
     /// </summary>
@@ -1667,7 +1693,8 @@ public bool Equals(VersionOptions? x, VersionOptions? y)
                 && NuGetPackageVersionOptions.EqualWithDefaultsComparer.Singleton.Equals(x.NuGetPackageVersionOrDefault, y.NuGetPackageVersionOrDefault)
                 && CloudBuildOptions.EqualWithDefaultsComparer.Singleton.Equals(x.CloudBuildOrDefault, y.CloudBuildOrDefault)
                 && ReleaseOptions.EqualWithDefaultsComparer.Singleton.Equals(x.ReleaseOrDefault, y.ReleaseOrDefault)
-                && x.VersionHeightOffset == y.VersionHeightOffset;
+                && x.VersionHeightOffset == y.VersionHeightOffset
+                && EqualityComparer<SemanticVersion?>.Default.Equals(x.VersionHeightOffsetAppliesTo, y.VersionHeightOffsetAppliesTo);
         }
 
         /// <inheritdoc />

src/NerdBank.GitVersioning/VersionOptionsContractResolver.cs

@@ -86,6 +86,11 @@ protected override JsonProperty CreateProperty(MemberInfo member, MemberSerializ
                 property.ShouldSerialize = instance => ((VersionOptions)instance).VersionHeightOffsetOrDefault != 0;
             }
 
+            if (property.DeclaringType == typeof(VersionOptions) && member.Name == nameof(VersionOptions.VersionHeightOffsetAppliesTo))
+            {
+                property.ShouldSerialize = instance => ((VersionOptions)instance).VersionHeightOffsetAppliesTo is not null;
+            }
+
             if (property.DeclaringType == typeof(VersionOptions) && member.Name == nameof(VersionOptions.NuGetPackageVersion))
             {
                 property.ShouldSerialize = instance => !((VersionOptions)instance).NuGetPackageVersionOrDefault.IsDefault;

src/NerdBank.GitVersioning/VersionOracle.cs

@@ -306,7 +306,34 @@ public string PrereleaseVersion
     /// when calculating the integer to use as the <see cref="BuildNumber"/>
     /// or elsewhere that the {height} macro is used.
     /// </summary>
-    public int VersionHeightOffset => this.VersionOptions?.VersionHeightOffsetOrDefault ?? 0;
+    public int VersionHeightOffset
+    {
+        get
+        {
+            if (this.VersionOptions is null)
+            {
+                return 0;
+            }
+
+            // Check if the offset applies to the current version
+            if (this.VersionOptions.VersionHeightOffsetAppliesTo is object &&
+                this.VersionOptions.Version is object &&
+                this.VersionOptions.VersionHeightPosition.HasValue)
+            {
+                // If the version would be reset by a change from VersionHeightOffsetAppliesTo to Version,
+                // then the offset does not apply.
+                if (SemanticVersion.WillVersionChangeResetVersionHeight(
+                    this.VersionOptions.VersionHeightOffsetAppliesTo,
+                    this.VersionOptions.Version,
+                    this.VersionOptions.VersionHeightPosition.Value))
+                {
+                    return 0;
+                }
+            }
+
+            return this.VersionOptions.VersionHeightOffsetOrDefault;
+        }
+    }
 
     /// <summary>
     /// Gets or sets the ref (branch or tag) being built.

src/NerdBank.GitVersioning/version.schema.json

@@ -68,6 +68,11 @@
           "description": "A number to add to the git height when calculating the version height (which typically appears as the 3rd integer in a computed version). May be negative, but not of greater magnitude than the original git height.",
           "default": 0
         },
+        "versionHeightOffsetAppliesTo": {
+          "type": "string",
+          "description": "The version to which the versionHeightOffset applies. When the version property changes such that the version height would be reset, and this property does not match the new version, the versionHeightOffset will be ignored. This allows the offset to implicitly reset as intended without having to manually remove it from all version.json files.",
+          "pattern": "^v?(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:\\.(0|[1-9][0-9]*)(?:\\.(0|[1-9][0-9]*))?)?(-(?:[\\da-z\\-]+|\\{height\\})(?:\\.(?:[\\da-z\\-]+|\\{height\\}))*)?(\\+(?:[\\da-z\\-]+|\\{height\\})(?:\\.(?:[\\da-z\\-]+|\\{height\\}))*)?$"
+        },
         "buildNumberOffset": {
           "type": "integer",
           "description": "OBSOLETE by v3.0. Use \"versionHeightOffset\" instead. A number to add to the git height when calculating the version height (which typically appears as the 3rd integer in a computed version). May be negative, but not of greater magnitude than the original git height.",