Add version management commands and update docs

- Consolidate UpdateVersion: patch increment (no args) or exact set (--VersionPrefix)
- Add ShowVersion target to display current version
- Rename to BuildTask.Targets.Version.cs
- Remove unused Bump parameter
- Update README, quick-start, and workflow guide with version commands

Made-with: Cursor

Author: Hongwei-MB

.nuke/build.schema.json

@@ -26,9 +26,12 @@
       "enum": [
         "Build",
         "Clean",
+        "GenerateReleaseManifest",
         "Pack",
+        "PackageApp",
         "Publish",
         "Restore",
+        "ShowVersion",
         "Test",
         "UpdateVersion"
       ]

README.md

@@ -96,11 +96,19 @@ The pipeline runs automatically. When `build-and-test` completes, go to **Action
 
 Versions follow a simple rule:
 
-- **Edit `VersionPrefix`** in `Directory.Build.props` via PR (e.g., `0.2.0` -> `1.0.0`)
 - **CI appends the build number** on release: `0.2.0` becomes `0.2.0.42`
 - **Tags are created automatically**: `v0.2.0.42`
+- No manual tagging. No version input fields. The single source of truth is `VersionPrefix` in `Directory.Build.props`.
 
-No manual tagging. No version input fields. Just change the number in one file.
+### Version commands
+
+```bash
+./build.sh ShowVersion                           # show current version
+./build.sh UpdateVersion                         # patch increment: 0.2.0 -> 0.2.1
+./build.sh UpdateVersion --VersionPrefix 1.0.0   # set exact version
+```
+
+Then commit and push -- CI takes care of the rest.
 
 ---
 

build/BuildTask.Parameters.cs

@@ -3,14 +3,6 @@
 
 partial class BuildTask
 {
-    // Stable external build interface (allowed CLI parameters):
-    //   - Configuration
-    //   - VersionPrefix  (used only by UpdateVersion target)
-    //   - VersionSuffix  (prerelease suffix, e.g., "ci.158")
-    //   - Runtime
-    //   - SelfContained
-    // VersionPrefix is owned by Directory.Build.props (single source of truth).
-
     [Parameter("Configuration to build - Default is 'Debug' (local) or 'Release' (server)")]
     readonly Configuration Configuration = IsLocalBuild ? Configuration.Debug : Configuration.Release;
 
@@ -20,6 +12,7 @@ partial class BuildTask
     [Parameter("Version suffix for prerelease builds (e.g., ci.158)")]
     readonly string VersionSuffix = string.Empty;
 
+
     // Internal path conventions controlled by build tasks (not external parameters).
     readonly string BuildPath = "Dotnet.CI.Template.slnx";
     readonly string TestPath = "Dotnet.CI.Template.slnx";

build/BuildTask.Targets.UpdateVersion.cs

@@ -0,0 +1,70 @@
+using System;
+using System.IO;
+using System.Text.RegularExpressions;
+using Nuke.Common;
+
+partial class BuildTask
+{
+    const string VersionPrefixPattern = @"<VersionPrefix>\s*([^<]+?)\s*</VersionPrefix>";
+
+    Target ShowVersion => _ => _
+        .Executes(() =>
+        {
+            Console.WriteLine($"Current VersionPrefix: {ReadCurrentVersionPrefix()}");
+        });
+
+    Target UpdateVersion => _ => _
+        .Executes(() =>
+        {
+            var current = ReadCurrentVersionPrefix();
+
+            if (!string.IsNullOrWhiteSpace(VersionPrefix))
+            {
+                if (!Regex.IsMatch(VersionPrefix, @"^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$"))
+                    throw new ArgumentException($"Invalid VersionPrefix: '{VersionPrefix}'. Expected semver format like 1.2.3 or 1.2.3-rc.1.");
+                WriteVersionPrefix(current, VersionPrefix);
+                return;
+            }
+
+            var next = PatchIncrement(current);
+            WriteVersionPrefix(current, next);
+        });
+
+    string ReadCurrentVersionPrefix()
+    {
+        var content = File.ReadAllText(DirectoryBuildPropsFile);
+        var match = Regex.Match(content, VersionPrefixPattern, RegexOptions.Singleline);
+        if (!match.Success)
+            throw new InvalidOperationException($"<VersionPrefix> not found in {DirectoryBuildPropsFile}");
+        return match.Groups[1].Value.Trim();
+    }
+
+    static string PatchIncrement(string current)
+    {
+        var baseVersion = current.Split('-')[0];
+        var parts = baseVersion.Split('.');
+        if (parts.Length < 3 || !int.TryParse(parts[0], out var major) || !int.TryParse(parts[1], out var minor) || !int.TryParse(parts[2], out var patch))
+            throw new InvalidOperationException($"Cannot parse current version '{current}' as X.Y.Z.");
+
+        return $"{major}.{minor}.{patch + 1}";
+    }
+
+    void WriteVersionPrefix(string current, string next)
+    {
+        if (string.Equals(current, next, StringComparison.OrdinalIgnoreCase))
+        {
+            Console.WriteLine($"VersionPrefix is already {next}.");
+            return;
+        }
+
+        var content = File.ReadAllText(DirectoryBuildPropsFile);
+        var updated = Regex.Replace(
+            content,
+            VersionPrefixPattern,
+            $"<VersionPrefix>{next}</VersionPrefix>",
+            RegexOptions.Singleline);
+
+        File.WriteAllText(DirectoryBuildPropsFile, updated);
+        Console.WriteLine($"Updated VersionPrefix: {current} -> {next}");
+    }
+}

build/BuildTask.Targets.Version.cs

@@ -102,7 +102,14 @@ push / PR to main + weekly
 版本来自 `Directory.Build.props` 的 `VersionPrefix`。CI 不接受手动输入版本参数。
 
 ### Q2: 如何升级版本？
-通过 PR 修改 `VersionPrefix`（例如 `0.1.0 -> 0.2.0`），合并到 `main` 后 CI 自动基于新版本构建。
+
+```bash
+./build.sh ShowVersion                           # 查看当前版本
+./build.sh UpdateVersion                         # patch 递增: 0.2.0 -> 0.2.1
+./build.sh UpdateVersion --VersionPrefix 1.0.0   # 精确设置
+```
+
+修改后通过 PR 合并到 `main`，CI 自动基于新版本构建。
 
 ### Q3: 同一版本能否重新发布？
 每次 main push 都会生成唯一的四段式版本号（如 `0.2.0.42`），因此同一 push 不会冲突。如果需要发新版本（如 `0.3.0`），通过 PR 修改 `VersionPrefix`。

docs/github-workflows-guide.md

@@ -48,10 +48,17 @@ resolve-version → build-and-test (matrix) → release (需 approve) → deploy
 
 ---
 
-## 4) 关于版本的两条规则（必读）
+## 4) 版本管理（必读）
 
-- 版本来自 `Directory.Build.props` 的 `VersionPrefix`，不需要也不能手填。
-- 如果要升级版本（例如 `0.1.0 -> 1.0.0`），先通过 PR 修改 `VersionPrefix` 并合并到 `main`，CI 自动基于新版本构建和发布。
+版本来自 `Directory.Build.props` 的 `VersionPrefix`，CI 自动追加 build number（如 `0.2.0.42`）。
+
+```bash
+./build.sh ShowVersion                           # 查看当前版本
+./build.sh UpdateVersion                         # patch 递增: 0.2.0 -> 0.2.1
+./build.sh UpdateVersion --VersionPrefix 1.0.0   # 精确设置
+```
+
+修改后提交到 `main`，CI 自动基于新版本构建和发布。
 
 ---