Configure package version update with delay

Author: bouwkast

.github/workflows/auto_bump_test_package_versions.yml.disabled

@@ -38,7 +38,21 @@ jobs:
           global-json-file: global.json
 
       - name: "Regenerating package versions"
-        run: .\tracer\build.ps1 GeneratePackageVersions
+        run: .\tracer\build.ps1 GeneratePackageVersions --PackageVersionCooldownDays 14
+
+      - name: Read cooldown report
+        id: cooldown
+        if: always()
+        shell: pwsh
+        run: |
+          $report = ""
+          $reportPath = "tracer/build/cooldown_report.md"
+          if (Test-Path $reportPath) {
+            $report = Get-Content $reportPath -Raw
+          }
+          "report<<EOF" >> $env:GITHUB_OUTPUT
+          $report >> $env:GITHUB_OUTPUT
+          "EOF" >> $env:GITHUB_OUTPUT
 
       - name: Create Pull Request
         id: pr
@@ -55,6 +69,8 @@ jobs:
           body: |
             Updates the package versions for integration tests.
 
+            ${{ steps.cooldown.outputs.report }}
+
       - name: Send Slack notification about generating failure
         if: failure()
         uses: slackapi/slack-github-action@91efab103c0de0a537f72a35f6b8cda0ee76bf0a # v2.1.1

.gitignore

@@ -405,3 +405,6 @@ tools/dumps/
 
 # test optimization temp/run folder
 .dd/
+
+# Generated by GeneratePackageVersions target (consumed by CI workflow, not committed)
+tracer/build/cooldown_report.md

tracer/build/_build/Build.Utilities.cs

@@ -59,6 +59,9 @@ partial class Build
     [Parameter("Only update package versions for packages with the following names")]
     readonly string[] IncludePackages;
 
+    [Parameter("Minimum age in days a NuGet package version must have been published before auto-including (default: 0, no filtering)")]
+    readonly int PackageVersionCooldownDays;
+
     [LazyLocalExecutable(@"C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools\gacutil.exe")]
     readonly Lazy<Tool> GacUtil;
     [LazyLocalExecutable(@"C:\Program Files\IIS Express\iisexpress.exe")]
@@ -247,11 +250,45 @@ partial class Build
            var previousSupportedVersions = await GenerateSupportMatrix.LoadPreviousVersions(supportedVersionsPath);
            Logger.Information("Loaded previous supported versions with {Count} entries", previousSupportedVersions.Count);
 
+           // Derive baseline from supported_versions.json: the max tested version per package
+           // acts as a floor to prevent cooldown filtering from downgrading previously accepted versions.
+           var baseline = previousSupportedVersions
+               .Where(kvp => kvp.Value.MaxVersionTestedInclusive is not null)
+               .GroupBy(kvp => kvp.Key.PackageName)
+               .ToDictionary(
+                   g => g.Key,
+                   g => g.Max(kvp => new Version(kvp.Value.MaxVersionTestedInclusive!)));
+           Logger.Information("Derived version baseline with {Count} entries from supported_versions.json", baseline.Count);
+
            // Pipeline A: generate .g.props/.g.cs files
-           var versionGenerator = new PackageVersionGenerator(TracerDirectory, testDir, shouldUpdatePackage, previousVersionCache);
+           Logger.Information("Using package version cooldown of {Days} days", PackageVersionCooldownDays);
+           var versionGenerator = new PackageVersionGenerator(TracerDirectory, testDir, shouldUpdatePackage, previousVersionCache, PackageVersionCooldownDays, baseline);
            var testedVersions = await versionGenerator.GenerateVersions(Solution);
            await NuGetVersionCache.Save(cacheFilePath, versionGenerator.VersionCache);
 
+           if (versionGenerator.CooldownReport.HasEntries)
+           {
+               Logger.Warning(
+                   "{Count} package version(s) were excluded due to the {Days}-day cooldown period",
+                   versionGenerator.CooldownReport.Entries.Count,
+                   PackageVersionCooldownDays);
+
+               foreach (var entry in versionGenerator.CooldownReport.Entries)
+               {
+                   var resolvedText = entry.ResolvedVersion is not null ? $"using: {entry.ResolvedVersion}" : "skipped";
+                   Logger.Warning(
+                       "  {Package} {Version} overridden (published {Date}, {Resolved})",
+                       entry.PackageName,
+                       entry.OverriddenVersion,
+                       entry.PublishedDate?.ToString("yyyy-MM-dd") ?? "unknown",
+                       resolvedText);
+               }
+
+               var reportPath = BuildDirectory / "cooldown_report.md";
+               await versionGenerator.CooldownReport.SaveToFile(reportPath);
+               Logger.Information("Cooldown report saved to {Path}", reportPath);
+           }
+
            var assemblies = MonitoringHomeDirectory
                            .GlobFiles("**/Datadog.Trace.dll")
                            .Select(x => x.ToString())
@@ -260,6 +297,8 @@ partial class Build
            var integrations = GenerateIntegrationDefinitions.GetAllIntegrations(assemblies, definitionsFile);
 
            // Pipeline B: generate dependabot files + supported_versions.json
+           // TestedVersions are cooldown-filtered but the baseline prevents downgrades,
+           // so they accurately reflect what we're testing.
            var distinctIntegrations = await DependabotFileManager.BuildDistinctIntegrationMaps(
                integrations, testedVersions, shouldUpdatePackage, previousSupportedVersions);
 

tracer/build/_build/GeneratePackageVersions/CooldownReport.cs

@@ -0,0 +1,88 @@
+// <copyright file="CooldownReport.cs" company="Datadog">
+// Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2 License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
+// </copyright>
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace GeneratePackageVersions;
+
+/// <summary>
+/// Collects package versions that were excluded by the cooldown filter
+/// and renders them as a markdown report for inclusion in the PR body.
+/// </summary>
+public class CooldownReport
+{
+    private readonly int _cooldownDays;
+    private readonly List<CooldownEntry> _entries = new();
+    private readonly HashSet<(string PackageName, string Version)> _seen = new();
+
+    public CooldownReport(int cooldownDays)
+    {
+        _cooldownDays = cooldownDays;
+    }
+
+    public bool HasEntries => _entries.Count > 0;
+
+    public IReadOnlyList<CooldownEntry> Entries => _entries;
+
+    public void Add(CooldownEntry entry)
+    {
+        // Deduplicate: the same version gets flagged once per framework and per selection group,
+        // but we only need to report it once.
+        if (_seen.Add((entry.PackageName, entry.OverriddenVersion)))
+        {
+            _entries.Add(entry);
+        }
+    }
+
+    public string ToMarkdown()
+    {
+        if (_entries.Count == 0)
+        {
+            return string.Empty;
+        }
+
+        var sb = new StringBuilder();
+        sb.AppendLine($"## Package Version Cooldown Report");
+        sb.AppendLine();
+        sb.AppendLine($"The following versions were published less than **{_cooldownDays} days** ago and have been overridden.");
+        sb.AppendLine("These require manual review before inclusion.");
+        sb.AppendLine();
+        sb.AppendLine("| Package | Integration | Overridden Version | Published | Age (days) | Using Instead |");
+        sb.AppendLine("|---------|-------------|--------------------|-----------|------------|---------------|");
+
+        foreach (var entry in _entries)
+        {
+            var published = entry.PublishedDate?.ToString("yyyy-MM-dd") ?? "unknown";
+            var age = entry.PublishedDate.HasValue
+                ? ((int)(DateTimeOffset.UtcNow - entry.PublishedDate.Value).TotalDays).ToString()
+                : "?";
+            var usingInstead = entry.ResolvedVersion ?? "(skipped)";
+
+            sb.AppendLine($"| {entry.PackageName} | {entry.IntegrationName} | {entry.OverriddenVersion} | {published} | {age} | {usingInstead} |");
+        }
+
+        return sb.ToString();
+    }
+
+    public async Task SaveToFile(string path)
+    {
+        var markdown = ToMarkdown();
+        if (!string.IsNullOrEmpty(markdown))
+        {
+            await File.WriteAllTextAsync(path, markdown);
+        }
+    }
+
+    public record CooldownEntry(
+        string PackageName,
+        string IntegrationName,
+        string OverriddenVersion,
+        DateTimeOffset? PublishedDate,
+        string ResolvedVersion);
+}

tracer/build/_build/GeneratePackageVersions/NuGetPackageHelper.cs

@@ -17,29 +17,32 @@ namespace GeneratePackageVersions
     public class NuGetPackageHelper
     {
         /// <summary>
-        /// Returns all available versions for a package, unfiltered by version range.
+        /// Returns all available versions for a package with their publish dates, unfiltered by version range.
         /// Suitable for caching since the result is independent of any specific entry's version bounds.
         /// </summary>
-        public static async Task<List<string>> GetAllNugetPackageVersions(string packageName)
+        public static async Task<List<VersionWithDate>> GetAllNugetPackageVersions(string packageName)
         {
             var searchMetadata = await GetPackageMetadatas(packageName);
 
-            var packageVersions = new List<string>();
+            var packageVersions = new List<VersionWithDate>();
             foreach (var md in searchMetadata)
             {
                 if (md.Identity.HasVersion)
                 {
-                    packageVersions.Add(md.Identity.Version.ToNormalizedString());
+                    packageVersions.Add(new VersionWithDate(
+                        md.Identity.Version.ToNormalizedString(),
+                        md.Published));
                 }
             }
 
             return packageVersions;
         }
 
         /// <summary>
-        /// Filters a list of version strings to only those within the entry's [MinVersion, MaxVersionExclusive) range.
+        /// Filters a list of versions to only those within the entry's [MinVersion, MaxVersionExclusive) range.
+        /// Preserves publish date metadata through the pipeline.
         /// </summary>
-        public static List<string> FilterVersions(IEnumerable<string> allVersions, IPackageVersionEntry entry)
+        public static List<VersionWithDate> FilterVersions(IEnumerable<VersionWithDate> allVersions, IPackageVersionEntry entry)
         {
             if (!NuGetVersion.TryParse(entry.MinVersion, out var minVersion))
             {
@@ -51,14 +54,14 @@ public static List<string> FilterVersions(IEnumerable<string> allVersions, IPack
                 throw new ArgumentException($"MaxVersion {entry.MaxVersionExclusive} in integration {entry.IntegrationName} could not be parsed into a NuGet Version");
             }
 
-            var result = new List<string>();
-            foreach (var versionText in allVersions)
+            var result = new List<VersionWithDate>();
+            foreach (var item in allVersions)
             {
-                if (NuGetVersion.TryParse(versionText, out var version)
+                if (NuGetVersion.TryParse(item.Version, out var version)
                     && version.CompareTo(minVersion) >= 0
                     && version.CompareTo(maxVersionExclusive) < 0)
                 {
-                    result.Add(versionText);
+                    result.Add(item);
                 }
             }
 

tracer/build/_build/GeneratePackageVersions/NuGetVersionCache.cs

@@ -25,35 +25,57 @@ public static class NuGetVersionCache
 
     /// <summary>
     /// Load the version cache from disk. Returns an empty dictionary if the file doesn't exist.
+    /// Handles both the old format (plain version strings) and the new format (version + publish date).
     /// </summary>
-    public static async Task<Dictionary<string, List<string>>> Load(string path)
+    public static async Task<Dictionary<string, List<VersionWithDate>>> Load(string path)
     {
         if (!File.Exists(path))
         {
-            return new Dictionary<string, List<string>>();
+            return new Dictionary<string, List<VersionWithDate>>();
         }
 
         await using var openStream = File.OpenRead(path);
 
-        var result = await JsonSerializer.DeserializeAsync<List<KeyValuePair<string, List<string>>>>(openStream, JsonOptions)
+        // Try new format first: List<KeyValuePair<string, List<VersionWithDate>>>
+        try
+        {
+            var result = await JsonSerializer.DeserializeAsync<List<KeyValuePair<string, List<VersionWithDate>>>>(openStream, JsonOptions);
+            if (result is not null)
+            {
+                return new Dictionary<string, List<VersionWithDate>>(result);
+            }
+        }
+        catch (JsonException)
+        {
+            // Fall through to old format
+        }
+
+        // Reset stream position for retry with old format
+        openStream.Position = 0;
+
+        // Old format: List<KeyValuePair<string, List<string>>>
+        var legacy = await JsonSerializer.DeserializeAsync<List<KeyValuePair<string, List<string>>>>(openStream, JsonOptions)
                      ?? new List<KeyValuePair<string, List<string>>>();
-        return new Dictionary<string, List<string>>(result);
+
+        return legacy.ToDictionary(
+            kvp => kvp.Key,
+            kvp => kvp.Value.Select(v => new VersionWithDate(v, null)).ToList());
     }
 
     /// <summary>
     /// Save the version cache to disk.
     /// </summary>
-    public static async Task Save(string path, Dictionary<string, List<string>> cache)
+    public static async Task Save(string path, Dictionary<string, List<VersionWithDate>> cache)
     {
         // convert to a list to make sure it has deterministic ordering
         var ordered = cache
             .OrderBy(x => x.Key)
-            .Select(x => new KeyValuePair<string, IEnumerable<string>>(
+            .Select(x => new KeyValuePair<string, IEnumerable<VersionWithDate>>(
                 x.Key,
                 x.Value
-                    .Select(Version.Parse)
-                    .OrderBy(version => version)
-                    .Select(version => version.ToString())));
+                    .Select(v => v with { Version = Version.Parse(v.Version).ToString() })
+                    .OrderBy(v => Version.Parse(v.Version))
+                    .ToList()));
         await using var createStream = File.Create(path);
         await JsonSerializer.SerializeAsync(createStream, ordered, JsonOptions);
     }