schedule-builder: optionally extend upcoming patch window to 4 during maintenance overlap

When the oldest supported minor (N-2) enters its maintenance window (i.e.
maintenanceModeStartDate <= today < endOfLifeDate), the next minor (N+1)
has typically already shipped, so four patch releases are concurrently
in flight. In that case three upcoming monthly patch entries no longer
cover the cycle.

Detect the overlap on the oldest entry in schedules[] and prompt the
operator (stderr, [y/N]) during --update. On confirmation, lift the
upcoming_releases[] cap from 3 to 4 for that run. TBD or unparseable
dates skip the prompt entirely. The schedules[] array is left alone:
adding a new minor entry remains a manual sig-release step.

The prompter is a package-level variable so tests can inject a
deterministic answer without touching stdin.

Signed-off-by: Nabarun Pal <pal.nabarun95@gmail.com>

Author: palnabarun

cmd/schedule-builder/cmd/markdown.go

@@ -17,9 +17,12 @@ limitations under the License.
 package cmd
 
 import (
+	"bufio"
 	"bytes"
 	"embed"
+	"errors"
 	"fmt"
+	"io"
 	"os"
 	"slices"
 	"strings"
@@ -188,8 +191,52 @@ const (
 # schedule-builder -uc data/releases/schedule.yaml -e data/releases/eol.yaml
 ---
 `
+	defaultUpcomingReleases  = 3
+	extendedUpcomingReleases = 4
 )
 
+// isInMaintenanceWindow reports whether refTime sits between sched's
+// maintenanceModeStartDate (inclusive) and endOfLifeDate (exclusive).
+// Unparseable values (commonly "TBD") return false.
+func isInMaintenanceWindow(refTime time.Time, sched *Schedule) bool {
+	if sched == nil || sched.MaintenanceModeStartDate == "" || sched.EndOfLifeDate == "" {
+		return false
+	}
+
+	mms, err := time.Parse(refDate, sched.MaintenanceModeStartDate)
+	if err != nil {
+		return false
+	}
+
+	eol, err := time.Parse(refDate, sched.EndOfLifeDate)
+	if err != nil {
+		return false
+	}
+
+	return !refTime.Before(mms) && refTime.Before(eol)
+}
+
+// confirmExtraUpcoming asks the operator whether to extend the upcoming
+// patch window to 4 entries during a maintenance-mode overlap. Overridable
+// in tests.
+var confirmExtraUpcoming = func(oldest *Schedule) (bool, error) {
+	fmt.Fprintf(os.Stderr,
+		"Oldest supported release %s is in its maintenance window "+
+			"(maintenanceModeStartDate=%s, endOfLifeDate=%s).\n"+
+			"Generate an additional upcoming patch release entry (%d total instead of %d)? [y/N]: ",
+		oldest.Release, oldest.MaintenanceModeStartDate, oldest.EndOfLifeDate,
+		extendedUpcomingReleases, defaultUpcomingReleases)
+
+	line, err := bufio.NewReader(os.Stdin).ReadString('\n')
+	if err != nil && !errors.Is(err, io.EOF) {
+		return false, fmt.Errorf("read confirmation: %w", err)
+	}
+
+	answer := strings.TrimSpace(strings.ToLower(line))
+
+	return answer == "y" || answer == "yes", nil
+}
+
 //nolint:maintidx // complex but acceptable
 func updatePatchSchedule(refTime time.Time, schedule PatchSchedule, eolBranches EolBranches, filePath, eolFilePath string) error {
 	removeSchedules := []int{}
@@ -321,6 +368,23 @@ func updatePatchSchedule(refTime time.Time, schedule PatchSchedule, eolBranches
 
 	schedule.Schedules = newSchedules
 
+	upcomingCap := defaultUpcomingReleases
+
+	if len(schedule.Schedules) > 0 {
+		oldest := schedule.Schedules[len(schedule.Schedules)-1]
+		if isInMaintenanceWindow(refTime, oldest) {
+			ok, err := confirmExtraUpcoming(oldest)
+			if err != nil {
+				return err
+			}
+
+			if ok {
+				upcomingCap = extendedUpcomingReleases
+				logrus.Infof("Extending upcoming patch window to %d entries while %s is in maintenance mode", extendedUpcomingReleases, oldest.Release)
+			}
+		}
+	}
+
 	newUpcomingReleases := []*PatchRelease{}
 	latestDate := refTime
 
@@ -342,8 +406,8 @@ func updatePatchSchedule(refTime time.Time, schedule PatchSchedule, eolBranches
 	}
 
 	for {
-		if len(newUpcomingReleases) >= 3 {
-			logrus.Infof("Got 3 new upcoming releases, not adding any more")
+		if len(newUpcomingReleases) >= upcomingCap {
+			logrus.Infof("Got %d new upcoming releases, not adding any more", upcomingCap)
 
 			break
 		}

cmd/schedule-builder/cmd/markdown_test.go

@@ -17,6 +17,7 @@ limitations under the License.
 package cmd
 
 import (
+	"errors"
 	"fmt"
 	"os"
 	"testing"
@@ -482,3 +483,132 @@ func TestUpdatePatchSchedule(t *testing.T) {
 		})
 	}
 }
+
+func TestUpdatePatchScheduleMaintenanceWindow(t *testing.T) {
+	refTime := time.Date(2026, 5, 24, 0, 0, 0, 0, time.UTC)
+
+	// Four supported minors with the oldest (1.30) sitting in its
+	// maintenance window relative to refTime. Each Next.TargetDate is
+	// after refTime so the per-schedule patch-bump loop short-circuits.
+	baseSchedule := func() PatchSchedule {
+		return PatchSchedule{
+			Schedules: []*Schedule{
+				{
+					Release: "1.33",
+					Next: &PatchRelease{
+						Release:            "1.33.1",
+						CherryPickDeadline: "2026-06-05",
+						TargetDate:         "2026-06-09",
+					},
+					EndOfLifeDate:            "2027-06-01",
+					MaintenanceModeStartDate: "2027-03-01",
+				},
+				{
+					Release: "1.32",
+					Next: &PatchRelease{
+						Release:            "1.32.5",
+						CherryPickDeadline: "2026-06-05",
+						TargetDate:         "2026-06-09",
+					},
+					EndOfLifeDate:            "2027-02-01",
+					MaintenanceModeStartDate: "2026-11-01",
+				},
+				{
+					Release: "1.31",
+					Next: &PatchRelease{
+						Release:            "1.31.10",
+						CherryPickDeadline: "2026-06-05",
+						TargetDate:         "2026-06-09",
+					},
+					EndOfLifeDate:            "2026-10-01",
+					MaintenanceModeStartDate: "2026-08-01",
+				},
+				{
+					Release: "1.30",
+					Next: &PatchRelease{
+						Release:            "1.30.15",
+						CherryPickDeadline: "2026-06-05",
+						TargetDate:         "2026-06-09",
+					},
+					EndOfLifeDate:            "2026-07-01",
+					MaintenanceModeStartDate: "2026-04-01",
+				},
+			},
+		}
+	}
+
+	for _, tc := range []struct {
+		name              string
+		confirm           func(*Schedule) (bool, error)
+		mutate            func(PatchSchedule) PatchSchedule
+		wantUpcomingCount int
+		wantErr           string
+	}{
+		{
+			name:              "overlap accepted - extends upcoming to 4",
+			confirm:           func(*Schedule) (bool, error) { return true, nil },
+			wantUpcomingCount: 4,
+		},
+		{
+			name:              "overlap declined - upcoming stays at 3",
+			confirm:           func(*Schedule) (bool, error) { return false, nil },
+			wantUpcomingCount: 3,
+		},
+		{
+			name: "TBD maintenance date - prompter never called",
+			confirm: func(*Schedule) (bool, error) {
+				t.Fatal("confirmExtraUpcoming must not be called when MaintenanceModeStartDate is TBD")
+
+				return false, nil
+			},
+			mutate: func(s PatchSchedule) PatchSchedule {
+				s.Schedules[3].MaintenanceModeStartDate = "TBD"
+
+				return s
+			},
+			wantUpcomingCount: 3,
+		},
+		{
+			name:    "prompt error bubbles up",
+			confirm: func(*Schedule) (bool, error) { return false, errors.New("boom") },
+			wantErr: "boom",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			orig := confirmExtraUpcoming
+
+			t.Cleanup(func() {
+				confirmExtraUpcoming = orig
+			})
+
+			confirmExtraUpcoming = tc.confirm
+
+			sched := baseSchedule()
+			if tc.mutate != nil {
+				sched = tc.mutate(sched)
+			}
+
+			scheduleFile, err := os.CreateTemp(t.TempDir(), "schedule-")
+			require.NoError(t, err)
+			require.NoError(t, scheduleFile.Close())
+
+			err = updatePatchSchedule(refTime, sched, EolBranches{}, scheduleFile.Name(), "")
+			if tc.wantErr != "" {
+				require.ErrorContains(t, err, tc.wantErr)
+
+				return
+			}
+
+			require.NoError(t, err)
+
+			scheduleYamlBytes, err := os.ReadFile(scheduleFile.Name()) //nolint:gosec // G304 - temp file path is safe
+			require.NoError(t, err)
+
+			patchRes := PatchSchedule{}
+			require.NoError(t, yaml.UnmarshalStrict(scheduleYamlBytes, &patchRes))
+
+			assert.Len(t, patchRes.UpcomingReleases, tc.wantUpcomingCount)
+			assert.Len(t, patchRes.Schedules, 4, "schedules[] count must be unchanged")
+		})
+	}
+}