[build] Rework changelog generation

- All changelog files (including headers, details, footers) are extracted to branch `docs-changelog`, which is cloned to `docs/_changelog`
- Rework build changelog tasks

Author: AndreyAkinshin

.github/workflows/generate-changelog.yaml

@@ -19,17 +19,17 @@ jobs:
       with:
         ref: master
 
-    - name: Download changelog
-      run: ./build.cmd docs-update --depth 1 --preview
+    - name: Fetch changelog
+      run: ./build.cmd docs-fetch --depth 1 --preview
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
     - name: Push changelog
       uses: JamesIves/[email protected]
       with:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        BRANCH: docs-changelog-details
-        FOLDER: docs/_changelog/details
+        BRANCH: docs-changelog
+        FOLDER: docs/_changelog
         GIT_CONFIG_NAME: Andrey Akinshin
         GIT_CONFIG_EMAIL: [email protected]
         CLEAN: true

.github/workflows/generate-gh-pages.yaml

@@ -22,8 +22,8 @@ jobs:
     - name: Build BenchmarkDotNet
       run: ./build.cmd build
 
-    - name: Download changelog
-      run: ./build.cmd docs-update --depth 1 --preview
+    - name: Fetch changelog
+      run: ./build.cmd docs-fetch --depth 1 --preview
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

build/BenchmarkDotNet.Build/BuildContext.cs

@@ -157,6 +157,7 @@ public void GenerateFile(FilePath filePath, StringBuilder content)
 
     public void GenerateFile(FilePath filePath, string content, bool reportNoChanges = false)
     {
+        this.EnsureDirectoryExists(filePath.GetDirectory());
         var relativePath = RootDirectory.GetRelativePath(filePath);
         if (this.FileExists(filePath))
         {

build/BenchmarkDotNet.Build/Meta/Repo.cs

@@ -12,7 +12,7 @@ public static class Repo
     public const string HttpsUrlBase = $"https://github.com/{Owner}/{Name}";
     public const string HttpsGitUrl =  $"{HttpsUrlBase}.git";
 
-    public const string ChangelogDetailsBranch = "docs-changelog-details";
+    public const string ChangelogBranch = "docs-changelog";
     public const string DocsStableBranch = "docs-stable";
     public const string MasterBranch = "master";
 

build/BenchmarkDotNet.Build/Program.cs

@@ -28,10 +28,10 @@ public HelpInfo GetHelp()
     {
         return new HelpInfo
         {
-            Examples = new[]
-            {
+            Examples =
+            [
                 new Example(Name)
-            }
+            ]
         };
     }
 }
@@ -48,10 +48,10 @@ public HelpInfo GetHelp()
     {
         return new HelpInfo
         {
-            Examples = new[]
-            {
+            Examples =
+            [
                 new Example(Name).WithMsBuildArgument("Configuration", "Debug")
-            }
+            ]
         };
     }
 }
@@ -68,10 +68,10 @@ public HelpInfo GetHelp()
     {
         return new HelpInfo
         {
-            Examples = new[]
-            {
+            Examples =
+            [
                 new Example(Name)
-            }
+            ]
         };
     }
 }
@@ -88,12 +88,12 @@ public HelpInfo GetHelp()
     {
         return new HelpInfo
         {
-            Examples = new[]
-            {
+            Examples =
+            [
                 new Example(Name)
                     .WithArgument(KnownOptions.Exclusive)
                     .WithArgument(KnownOptions.Verbosity, "Diagnostic")
-            }
+            ]
         };
     }
 }
@@ -145,68 +145,68 @@ public HelpInfo GetHelp()
     {
         return new HelpInfo
         {
-            Examples = new[]
-            {
+            Examples =
+            [
                 new Example(Name)
                     .WithMsBuildArgument("VersionPrefix", "0.1.1729")
                     .WithMsBuildArgument("VersionSuffix", "preview"),
                 new Example(Name).WithArgument(KnownOptions.Stable)
-            }
+            ]
         };
     }
 }
 
 [TaskName(Name)]
-[TaskDescription("Update generated documentation files")]
-public class DocsUpdateTask : FrostingTask<BuildContext>, IHelpProvider
+[TaskDescription("Fetch changelog files")]
+public class DocsFetchTask : FrostingTask<BuildContext>, IHelpProvider
 {
-    private const string Name = "docs-update";
-    public override void Run(BuildContext context) => context.DocumentationRunner.Update();
+    private const string Name = "docs-fetch";
+    public override void Run(BuildContext context) => context.DocumentationRunner.Fetch();
 
     public HelpInfo GetHelp()
     {
         return new HelpInfo
         {
             Description = $"This task updates the following files:\n" +
-                          $"* README.md (the number of dependent projects number)\n" +
+                          $"* Clones branch 'docs-changelog' to docs/_changelog\n" +
                           $"* Last changelog footer (if {KnownOptions.Stable.CommandLineName} is specified)\n" +
                           $"* All changelog details in docs/_changelog\n" +
-                          $"  (This dir is a cloned version of this repo from branch {Repo.ChangelogDetailsBranch})",
-            Options = new IOption[] { KnownOptions.DocsPreview, KnownOptions.DocsDepth },
-            EnvironmentVariables = new[] { EnvVar.GitHubToken },
-            Examples = new[]
-            {
+                          $"  (This dir is a cloned version of this repo from branch {Repo.ChangelogBranch})",
+            Options = [KnownOptions.DocsPreview, KnownOptions.DocsDepth],
+            EnvironmentVariables = [EnvVar.GitHubToken],
+            Examples =
+            [
                 new Example(Name)
                     .WithArgument(KnownOptions.DocsDepth, "3")
                     .WithArgument(KnownOptions.DocsPreview)
-            }
+            ]
         };
     }
 }
 
 [TaskName(Name)]
-[TaskDescription("Prepare auxiliary documentation files")]
-public class DocsPrepareTask : FrostingTask<BuildContext>, IHelpProvider
+[TaskDescription("Generate auxiliary documentation files")]
+public class DocsGenerateTask : FrostingTask<BuildContext>, IHelpProvider
 {
-    private const string Name = "docs-prepare";
-    public override void Run(BuildContext context) => context.DocumentationRunner.Prepare();
+    private const string Name = "docs-generate";
+    public override void Run(BuildContext context) => context.DocumentationRunner.Generate();
 
     public HelpInfo GetHelp()
     {
         return new HelpInfo
         {
-            Options = new IOption[] { KnownOptions.DocsPreview },
-            Examples = new[]
-            {
+            Options = [KnownOptions.DocsPreview],
+            Examples =
+            [
                 new Example(Name).WithArgument(KnownOptions.DocsPreview)
-            }
+            ]
         };
     }
 }
 
 [TaskName(Name)]
 [TaskDescription("Build final documentation")]
-[IsDependentOn(typeof(DocsPrepareTask))]
+[IsDependentOn(typeof(DocsGenerateTask))]
 public class DocsBuildTask : FrostingTask<BuildContext>, IHelpProvider
 {
     private const string Name = "docs-build";
@@ -215,19 +215,20 @@ public class DocsBuildTask : FrostingTask<BuildContext>, IHelpProvider
     public HelpInfo GetHelp() => new()
     {
         Description = "The 'build' task should be run manually to build api docs",
-        Options = new IOption[] { KnownOptions.DocsPreview },
-        Examples = new[]
-        {
+        Options = [KnownOptions.DocsPreview],
+        Examples =
+        [
             new Example(Name).WithArgument(KnownOptions.DocsPreview)
-        }
+        ]
     };
 }
 
 [TaskName(Name)]
 [TaskDescription("Release new version")]
 [IsDependentOn(typeof(BuildTask))]
 [IsDependentOn(typeof(PackTask))]
-[IsDependentOn(typeof(DocsUpdateTask))]
+[IsDependentOn(typeof(DocsFetchTask))]
+[IsDependentOn(typeof(DocsGenerateTask))]
 [IsDependentOn(typeof(DocsBuildTask))]
 public class ReleaseTask : FrostingTask<BuildContext>, IHelpProvider
 {
@@ -236,17 +237,17 @@ public class ReleaseTask : FrostingTask<BuildContext>, IHelpProvider
 
     public HelpInfo GetHelp() => new()
     {
-        Options = new IOption[] { KnownOptions.NextVersion, KnownOptions.Push },
-        EnvironmentVariables = new[] { EnvVar.GitHubToken, EnvVar.NuGetToken },
-        Examples = new[]
-        {
+        Options = [KnownOptions.NextVersion, KnownOptions.Push],
+        EnvironmentVariables = [EnvVar.GitHubToken, EnvVar.NuGetToken],
+        Examples =
+        [
             new Example(Name)
                 .WithArgument(KnownOptions.Stable)
                 .WithArgument(KnownOptions.NextVersion, "0.1.1729")
                 .WithArgument(KnownOptions.Push),
             new Example(Name)
                 .WithArgument(KnownOptions.Stable)
                 .WithArgument(KnownOptions.Push)
-        }
+        ]
     };
 }