Merge pull request #1242 from dotnet/copilot/fix-1019

Add --what-if option to prepare-release command for simulating version changes

Author: AArnott

src/NerdBank.GitVersioning/ReleaseManager.cs

@@ -104,6 +104,12 @@ public enum ReleaseManagerOutputMode
         Json = 1,
     }
 
+    public void WriteToOutput(ReleaseInfo releaseInfo)
+    {
+        string json = JsonConvert.SerializeObject(releaseInfo, Formatting.Indented, new SemanticVersionJsonConverter());
+        this.stdout.WriteLine(json);
+    }
+
     /// <summary>
     /// Prepares a release for the specified directory by creating a release branch and incrementing the version in the current branch.
     /// </summary>
@@ -131,7 +137,70 @@ public enum ReleaseManagerOutputMode
     /// <param name="unformattedCommitMessage">
     /// An optional, custom message to use for the commit that sets the new version number. May use <c>{0}</c> to substitute the new version number.
     /// </param>
-    public void PrepareRelease(string projectDirectory, string releaseUnstableTag = null, Version nextVersion = null, VersionOptions.ReleaseVersionIncrement? versionIncrement = null, ReleaseManagerOutputMode outputMode = default, string unformattedCommitMessage = null)
+    /// <param name="whatIf">
+    /// If true, simulates the prepare-release operation and returns the versions that would be set without making any changes.
+    /// </param>
+    /// <returns>
+    /// A <see cref="ReleaseInfo"/> object containing information about the release when <paramref name="whatIf"/> is true; otherwise null.
+    /// </returns>
+    public ReleaseInfo PrepareRelease(string projectDirectory, string releaseUnstableTag = null, Version nextVersion = null, VersionOptions.ReleaseVersionIncrement? versionIncrement = null, ReleaseManagerOutputMode outputMode = default, string unformattedCommitMessage = null, bool whatIf = false)
+    {
+        return this.PrepareReleaseCore(projectDirectory, releaseUnstableTag, nextVersion, versionIncrement, outputMode, unformattedCommitMessage, whatIf);
+    }
+
+    private static bool IsVersionDecrement(SemanticVersion oldVersion, SemanticVersion newVersion)
+    {
+        if (newVersion.Version > oldVersion.Version)
+        {
+            return false;
+        }
+        else if (newVersion.Version == oldVersion.Version)
+        {
+            return string.IsNullOrEmpty(oldVersion.Prerelease) &&
+                  !string.IsNullOrEmpty(newVersion.Prerelease);
+        }
+        else
+        {
+            // newVersion.Version < oldVersion.Version
+            return true;
+        }
+    }
+
+    /// <summary>
+    /// Core implementation of prepare-release functionality that can either simulate or execute the operation.
+    /// </summary>
+    /// <param name="projectDirectory">
+    /// The path to the directory that may (or its ancestors may) define the version file.
+    /// </param>
+    /// <param name="releaseUnstableTag">
+    /// An optional prerelease tag to apply on the release branch.
+    /// If not specified, any existing prerelease tag will be removed from the release.
+    /// The preceding hyphen may be omitted.
+    /// </param>
+    /// <param name="nextVersion">
+    /// The version to use for the next release.
+    /// If not specified, the next version will be determined automatically by incrementing the current
+    /// version based on the current version and the <paramref name="versionIncrement"/> setting in <c>version.json</c>.
+    /// Parameter will be ignored if the current branch is a release branch.
+    /// </param>
+    /// <param name="versionIncrement">
+    /// The increment to apply in order to determine the next version on the current branch.
+    /// If specified, value will be used instead of the increment specified in <c>version.json</c>.
+    /// Parameter will be ignored if the current branch is a release branch.
+    /// </param>
+    /// <param name="outputMode">
+    /// The output format to use for writing to stdout.
+    /// </param>
+    /// <param name="unformattedCommitMessage">
+    /// An optional, custom message to use for the commit that sets the new version number. May use <c>{0}</c> to substitute the new version number.
+    /// </param>
+    /// <param name="whatIf">
+    /// If true, simulates the prepare-release operation and returns the versions that would be set without making any changes.
+    /// </param>
+    /// <returns>
+    /// A <see cref="ReleaseInfo"/> object containing information about the release when <paramref name="whatIf"/> is true; otherwise null.
+    /// </returns>
+    private ReleaseInfo PrepareReleaseCore(string projectDirectory, string releaseUnstableTag, Version nextVersion, VersionOptions.ReleaseVersionIncrement? versionIncrement, ReleaseManagerOutputMode outputMode, string unformattedCommitMessage, bool whatIf)
     {
         Requires.NotNull(projectDirectory, nameof(projectDirectory));
 
@@ -164,16 +233,30 @@ public void PrepareRelease(string projectDirectory, string releaseUnstableTag =
         {
             if (outputMode == ReleaseManagerOutputMode.Text)
             {
-                this.stdout.WriteLine($"{releaseBranchName} branch advanced from {versionOptions.Version} to {releaseVersion}.");
+                if (whatIf)
+                {
+                    this.stdout.WriteLine($"What-if: {releaseBranchName} branch would be advanced from {versionOptions.Version} to {releaseVersion}.");
+                }
+                else
+                {
+                    this.stdout.WriteLine($"{releaseBranchName} branch advanced from {versionOptions.Version} to {releaseVersion}.");
+                }
+            }
+
+            var releaseInfo = new ReleaseInfo(new ReleaseBranchInfo(releaseBranchName, repository.Head.Tip.Id.ToString(), releaseVersion));
+
+            if (whatIf)
+            {
+                return releaseInfo;
             }
-            else
+
+            if (outputMode == ReleaseManagerOutputMode.Json)
             {
-                var releaseInfo = new ReleaseInfo(new ReleaseBranchInfo(releaseBranchName, repository.Head.Tip.Id.ToString(), releaseVersion));
                 this.WriteToOutput(releaseInfo);
             }
 
             this.UpdateVersion(context, versionOptions.Version, releaseVersion, unformattedCommitMessage);
-            return;
+            return null;
         }
 
         SemanticVersion nextDevVersion = this.GetNextDevVersion(versionOptions, nextVersion, versionIncrement);
@@ -193,6 +276,21 @@ public void PrepareRelease(string projectDirectory, string releaseUnstableTag =
             throw new ReleasePreparationException(ReleasePreparationError.BranchAlreadyExists);
         }
 
+        if (outputMode == ReleaseManagerOutputMode.Text && whatIf)
+        {
+            this.stdout.WriteLine($"What-if: {releaseBranchName} branch would track v{releaseVersion} stabilization and release.");
+            this.stdout.WriteLine($"What-if: {originalBranchName} branch would track v{nextDevVersion} development.");
+        }
+
+        var originalBranchInfo = new ReleaseBranchInfo(originalBranchName, repository.Head.Tip.Sha, nextDevVersion);
+        var releaseBranchInfo = new ReleaseBranchInfo(releaseBranchName, repository.Head.Tip.Id.ToString(), releaseVersion);
+        var releaseInfoResult = new ReleaseInfo(originalBranchInfo, releaseBranchInfo);
+
+        if (whatIf)
+        {
+            return releaseInfoResult;
+        }
+
         // create release branch and update version
         Branch releaseBranch = repository.CreateBranch(releaseBranchName);
         global::LibGit2Sharp.Commands.Checkout(repository, releaseBranch);
@@ -222,30 +320,15 @@ public void PrepareRelease(string projectDirectory, string releaseUnstableTag =
 
         if (outputMode == ReleaseManagerOutputMode.Json)
         {
-            var originalBranchInfo = new ReleaseBranchInfo(originalBranchName, repository.Head.Tip.Sha, nextDevVersion);
-            var releaseBranchInfo = new ReleaseBranchInfo(releaseBranchName, repository.Branches[releaseBranchName].Tip.Id.ToString(), releaseVersion);
-            var releaseInfo = new ReleaseInfo(originalBranchInfo, releaseBranchInfo);
+            // Update the commit IDs with the actual final commit IDs after all operations
+            var finalOriginalBranchInfo = new ReleaseBranchInfo(originalBranchName, repository.Head.Tip.Sha, nextDevVersion);
+            var finalReleaseBranchInfo = new ReleaseBranchInfo(releaseBranchName, repository.Branches[releaseBranchName].Tip.Id.ToString(), releaseVersion);
+            var finalReleaseInfo = new ReleaseInfo(finalOriginalBranchInfo, finalReleaseBranchInfo);
 
-            this.WriteToOutput(releaseInfo);
+            this.WriteToOutput(finalReleaseInfo);
         }
-    }
 
-    private static bool IsVersionDecrement(SemanticVersion oldVersion, SemanticVersion newVersion)
-    {
-        if (newVersion.Version > oldVersion.Version)
-        {
-            return false;
-        }
-        else if (newVersion.Version == oldVersion.Version)
-        {
-            return string.IsNullOrEmpty(oldVersion.Prerelease) &&
-                  !string.IsNullOrEmpty(newVersion.Prerelease);
-        }
-        else
-        {
-            // newVersion.Version < oldVersion.Version
-            return true;
-        }
+        return null;
     }
 
     private string GetReleaseBranchName(VersionOptions versionOptions)
@@ -387,12 +470,6 @@ private SemanticVersion GetNextDevVersion(VersionOptions versionOptions, Version
         return nextDevVersion.SetFirstPrereleaseTag(versionOptions.ReleaseOrDefault.FirstUnstableTagOrDefault);
     }
 
-    private void WriteToOutput(ReleaseInfo releaseInfo)
-    {
-        string json = JsonConvert.SerializeObject(releaseInfo, Formatting.Indented, new SemanticVersionJsonConverter());
-        this.stdout.WriteLine(json);
-    }
-
     /// <summary>
     /// Exception indicating an error during preparation of a release.
     /// </summary>

src/nbgv/Program.cs

@@ -98,7 +98,6 @@ private static RootCommand BuildCommandLine()
                 var source = new Option<string[]>("--source", ["-s"])
                 {
                     Description = $"The URI(s) of the NuGet package source(s) used to determine the latest stable version of the {PackageId} package. This setting overrides all of the sources specified in the NuGet.Config files.",
-                    DefaultValueFactory = _ => Array.Empty<string>(),
                     Arity = ArgumentArity.OneOrMore,
                     AllowMultipleArgumentsPerToken = true,
                 };
@@ -123,7 +122,7 @@ private static RootCommand BuildCommandLine()
                 {
                     Description = "The path to the project or project directory. The default is the current directory.",
                 };
-                var metadata = new Option<string[]>("--metadata", Array.Empty<string>())
+                var metadata = new Option<string[]>("--metadata")
                 {
                     Description = "Adds an identifier to the build metadata part of a semantic version.",
                     Arity = ArgumentArity.OneOrMore,
@@ -262,7 +261,7 @@ private static RootCommand BuildCommandLine()
                 {
                     Description = "The path to the project or project directory used to calculate the version. The default is the current directory. Ignored if the -v option is specified.",
                 };
-                var metadata = new Option<string[]>("--metadata", Array.Empty<string>())
+                var metadata = new Option<string[]>("--metadata")
                 {
                     Description = "Adds an identifier to the build metadata part of a semantic version.",
                     Arity = ArgumentArity.OneOrMore,
@@ -284,14 +283,13 @@ private static RootCommand BuildCommandLine()
                 {
                     Description = "Defines a few common version variables as cloud build variables, with a \"Git\" prefix (e.g. GitBuildVersion, GitBuildVersionSimple, GitAssemblyInformationalVersion).",
                 };
-                var skipCloudBuildNumber = new Option<bool>("--skip-cloud-build-number", Array.Empty<string>())
+                var skipCloudBuildNumber = new Option<bool>("--skip-cloud-build-number")
                 {
                     Description = "Do not emit the cloud build variable to set the build number. This is useful when you want to set other cloud build variables but not the build number.",
                 };
                 var define = new Option<string[]>("--define", ["-d"])
                 {
                     Description = "Additional cloud build variables to define. Each should be in the NAME=VALUE syntax.",
-                    DefaultValueFactory = _ => Array.Empty<string>(),
                     Arity = ArgumentArity.OneOrMore,
                     AllowMultipleArgumentsPerToken = true,
                 };
@@ -327,22 +325,26 @@ private static RootCommand BuildCommandLine()
                 {
                     Description = "The path to the project or project directory. The default is the current directory.",
                 };
-                var nextVersion = new Option<string>("--nextVersion", Array.Empty<string>())
+                var nextVersion = new Option<string>("--nextVersion")
                 {
                     Description = "The version to set for the current branch. If omitted, the next version is determined automatically by incrementing the current version.",
                 };
-                var versionIncrement = new Option<string>("--versionIncrement", Array.Empty<string>())
+                var versionIncrement = new Option<string>("--versionIncrement")
                 {
                     Description = "Overrides the 'versionIncrement' setting set in version.json for determining the next version of the current branch.",
                 };
                 var format = new Option<string>("--format", ["-f"])
                 {
                     Description = $"The format to write information about the release. Allowed values are: {string.Join(", ", SupportedFormats)}. The default is {DefaultOutputFormat}.",
                 };
-                var unformattedCommitMessage = new Option<string>("--commit-message-pattern", Array.Empty<string>())
+                var unformattedCommitMessage = new Option<string>("--commit-message-pattern")
                 {
                     Description = "A custom message to use for the commit that changes the version number. May include {0} for the version number. If not specified, the default is \"Set version to '{0}'\".",
                 };
+                var whatIf = new Option<bool>("--what-if")
+                {
+                    Description = "Simulates the prepare-release operation and prints the new version that would be set, but does not actually make any changes.",
+                };
                 var tagArgument = new Argument<string>("tag")
                 {
                     Description = "The prerelease tag to apply on the release branch (if any). If not specified, any existing prerelease tag will be removed. The preceding hyphen may be omitted.",
@@ -355,6 +357,7 @@ private static RootCommand BuildCommandLine()
                     versionIncrement,
                     format,
                     unformattedCommitMessage,
+                    whatIf,
                     tagArgument,
                 };
 
@@ -366,7 +369,8 @@ private static RootCommand BuildCommandLine()
                     var formatValue = parseResult.GetValue(format);
                     var tagArgumentValue = parseResult.GetValue(tagArgument);
                     var unformattedCommitMessageValue = parseResult.GetValue(unformattedCommitMessage);
-                    return await OnPrepareReleaseCommand(projectValue, nextVersionValue, versionIncrementValue, formatValue, tagArgumentValue, unformattedCommitMessageValue);
+                    var whatIfValue = parseResult.GetValue(whatIf);
+                    return await OnPrepareReleaseCommand(projectValue, nextVersionValue, versionIncrementValue, formatValue, tagArgumentValue, unformattedCommitMessageValue, whatIfValue);
                 });
             }
 
@@ -915,7 +919,7 @@ private static Task<int> OnCloudCommand(string project, string[] metadata, strin
             return Task.FromResult((int)ExitCodes.OK);
         }
 
-        private static Task<int> OnPrepareReleaseCommand(string project, string nextVersion, string versionIncrement, string format, string tag, string unformattedCommitMessage)
+        private static Task<int> OnPrepareReleaseCommand(string project, string nextVersion, string versionIncrement, string format, string tag, string unformattedCommitMessage, bool whatIf)
         {
             // validate project path property
             string searchPath = GetSpecifiedOrCurrentDirectoryPath(project);
@@ -981,11 +985,18 @@ private static Task<int> OnPrepareReleaseCommand(string project, string nextVers
                 }
             }
 
-            // run prepare-release
+            // run prepare-release or simulate
             try
             {
                 var releaseManager = new ReleaseManager(Console.Out, Console.Error);
-                releaseManager.PrepareRelease(searchPath, tag, nextVersionParsed, versionIncrementParsed, outputMode, unformattedCommitMessage);
+
+                ReleaseManager.ReleaseInfo releaseInfo = releaseManager.PrepareRelease(searchPath, tag, nextVersionParsed, versionIncrementParsed, outputMode, unformattedCommitMessage, whatIf);
+
+                if (whatIf && outputMode == ReleaseManager.ReleaseManagerOutputMode.Json)
+                {
+                    releaseManager.WriteToOutput(releaseInfo);
+                }
+
                 return Task.FromResult((int)ExitCodes.OK);
             }
             catch (ReleaseManager.ReleasePreparationException ex)