Add handling for speculative matches in content source logic (#1297)

This will flag version branches as a speculative match ensuring we'll onboard new version branches before they are actively marked as current / next.

If a current branch is already a version branch we will only build new version branches speculatively.

This also ensures new repositories will speculatively build for `main` / `master` or version branches.

Author: Mpdreamz

.github/workflows/preview-build.yml

@@ -81,7 +81,7 @@ jobs:
         run: |
           echo "Non sensitive data, echo'ing here temporarily to validate this job before connecting it further into the build job"
           echo "content-source-match=${{ steps.event-check.outputs.content-source-match != '' && steps.event-check.outputs.content-source-match || steps.match.outputs.content-source-match }}"
-          echo "content-source-name=${{ steps.event-check.outputs.content-source-next != '' && steps.event-check.outputs.content-source-next || steps.match.outputs.content-source-next }}"
+          echo "content-source-next=${{ steps.event-check.outputs.content-source-next != '' && steps.event-check.outputs.content-source-next || steps.match.outputs.content-source-next }}"
           echo "content-source-current=${{ steps.event-check.outputs.content-source-current != '' && steps.event-check.outputs.content-source-current || steps.match.outputs.content-source-current }}"
           echo "ref=${{ github.ref_name }}"
           echo "repo=${{ github.repository }}"

actions/assembler-match/action.yml

@@ -20,6 +20,8 @@ outputs:
     description: "true/false indicating the branch acts as the next content source"
   content-source-current:
     description: "true/false indicating the branch acts as the current content source"
+  content-source-speculative:
+    description: "true/false speculative match, used to build version branches before they are marked as current/next"
 
 runs:
   using: 'docker'

src/Elastic.Documentation.Configuration/Assembler/AssemblyConfiguration.cs

@@ -2,6 +2,7 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using System.Text.RegularExpressions;
 using Elastic.Documentation.Serialization;
 using YamlDotNet.Serialization;
 using YamlStaticContext = Elastic.Documentation.Configuration.Serialization.YamlStaticContext;
@@ -83,19 +84,45 @@ private static TRepository RepositoryDefaults<TRepository>(TRepository r, string
 	/// <paramref name="repository"/>.
 	public ContentSourceMatch Match(string repository, string branchOrTag)
 	{
-		var repositoryName = repository.Split('/').Last();
-		var match = new ContentSourceMatch(null, null);
+		var match = new ContentSourceMatch(null, null, false);
+		var tokens = repository.Split('/');
+		var repositoryName = tokens.Last();
+		var owner = tokens.First();
+
+		if (tokens.Length < 2 || owner != "elastic")
+			return match;
+
 		if (ReferenceRepositories.TryGetValue(repositoryName, out var r))
 		{
-			if (r.GetBranch(ContentSource.Current) == branchOrTag)
+			var current = r.GetBranch(ContentSource.Current);
+			var next = r.GetBranch(ContentSource.Next);
+			var isVersionBranch = ContentSourceRegex.MatchVersionBranch().IsMatch(branchOrTag);
+			if (current == branchOrTag)
 				match = match with { Current = ContentSource.Current };
-			if (r.GetBranch(ContentSource.Next) == branchOrTag)
+			if (next == branchOrTag)
 				match = match with { Next = ContentSource.Next };
+			if (isVersionBranch && SemVersion.TryParse(branchOrTag + ".0", out var v))
+			{
+				// if the current branch is a version, only speculatively match if branch is actually a new version
+				if (SemVersion.TryParse(current + ".0", out var currentVersion))
+				{
+					if (v >= currentVersion)
+						match = match with { Speculative = true };
+				}
+				// assume we are newly onboarding the repository to current/next
+				else
+					match = match with { Speculative = true };
+			}
 			return match;
 		}
 
 		if (repositoryName != NarrativeRepository.RepositoryName)
-			return match;
+		{
+			// this is an unknown new elastic repository
+			var isVersionBranch = ContentSourceRegex.MatchVersionBranch().IsMatch(branchOrTag);
+			if (isVersionBranch || branchOrTag == "main" || branchOrTag == "master")
+				return match with { Speculative = true };
+		}
 
 		if (Narrative.GetBranch(ContentSource.Current) == branchOrTag)
 			match = match with { Current = ContentSource.Current };
@@ -105,5 +132,12 @@ public ContentSourceMatch Match(string repository, string branchOrTag)
 		return match;
 	}
 
-	public record ContentSourceMatch(ContentSource? Current, ContentSource? Next);
+	public record ContentSourceMatch(ContentSource? Current, ContentSource? Next, bool Speculative);
+
+}
+
+internal static partial class ContentSourceRegex
+{
+	[GeneratedRegex(@"^\d+\.\d+$", RegexOptions.IgnoreCase, "en-US")]
+	public static partial Regex MatchVersionBranch();
 }

src/Elastic.Markdown/Helpers/SemVersion.cs renamed to src/Elastic.Documentation/SemVersion.cs

@@ -6,7 +6,7 @@
 using System.Globalization;
 using System.Text.RegularExpressions;
 
-namespace Elastic.Markdown.Helpers;
+namespace Elastic.Documentation;
 
 /// <summary>
 /// A semver2 compatible version.

src/Elastic.Markdown/Myst/Directives/VersionBlock.cs

@@ -2,6 +2,7 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using Elastic.Documentation;
 using Elastic.Markdown.Diagnostics;
 using Elastic.Markdown.Helpers;
 using static System.StringSplitOptions;

src/Elastic.Markdown/Myst/FrontMatter/AllVersions.cs

@@ -2,6 +2,7 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using Elastic.Documentation;
 using Elastic.Markdown.Helpers;
 using YamlDotNet.Core;
 using YamlDotNet.Core.Events;

src/Elastic.Markdown/Myst/FrontMatter/Applicability.cs

@@ -5,6 +5,7 @@
 using System.Collections;
 using System.Diagnostics.CodeAnalysis;
 using System.Text;
+using Elastic.Documentation;
 using Elastic.Markdown.Helpers;
 using YamlDotNet.Serialization;
 

src/Elastic.Markdown/Myst/Roles/AppliesTo/AppliesToRole.cs

@@ -3,6 +3,7 @@
 // See the LICENSE file in the project root for more information
 
 using System.Diagnostics;
+using Elastic.Documentation;
 using Elastic.Markdown.Diagnostics;
 using Elastic.Markdown.Helpers;
 using Elastic.Markdown.Myst.FrontMatter;

src/tooling/docs-assembler/Cli/ContentSourceCommands.cs

@@ -55,12 +55,13 @@ public async Task<int> Match([Argument] string? repository = null, [Argument] st
 			AllowIndexing = false
 		};
 		var matches = assembleContext.Configuration.Match(repo, refName);
-		if (matches is { Current: null, Next: null })
+		if (matches is { Current: null, Next: null, Speculative: false })
 		{
 			logger.LogInformation("'{Repository}' '{BranchOrTag}' combination not found in configuration.", repo, refName);
 			await githubActionsService.SetOutputAsync("content-source-match", "false");
 			await githubActionsService.SetOutputAsync("content-source-next", "false");
 			await githubActionsService.SetOutputAsync("content-source-current", "false");
+			await githubActionsService.SetOutputAsync("content-source-speculative", "false");
 		}
 		else
 		{
@@ -72,6 +73,7 @@ public async Task<int> Match([Argument] string? repository = null, [Argument] st
 			await githubActionsService.SetOutputAsync("content-source-match", "true");
 			await githubActionsService.SetOutputAsync("content-source-next", matches.Next is not null ? "true" : "false");
 			await githubActionsService.SetOutputAsync("content-source-current", matches.Current is not null ? "true" : "false");
+			await githubActionsService.SetOutputAsync("content-source-speculative", matches.Speculative ? "true" : "false");
 		}
 
 		await collector.StopAsync(ctx);

src/tooling/docs-builder/Cli/CheckForUpdatesFilter.cs

@@ -4,6 +4,7 @@
 
 using System.Reflection;
 using ConsoleAppFramework;
+using Elastic.Documentation;
 using Elastic.Markdown.Helpers;
 using Elastic.Markdown.IO;
 

tests/Elastic.Markdown.Tests/Directives/VersionTests.cs

@@ -2,6 +2,7 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using Elastic.Documentation;
 using Elastic.Markdown.Helpers;
 using Elastic.Markdown.Myst.Directives;
 using FluentAssertions;