Skip to content

Please Test v2.5 Beta! - breaking-change minor #5630

Closed
Closed
Please Test v2.5 Beta! - breaking-change minor#5630
Assignees
tig
Labels
breaking-changeFor PRs that introduces a breaking change (behavior or API)build-and-deployIssues regarding to building and deploying Terminal.GuidocsCan be resolved via a documentation updatev2
Milestone
v2.x

Description

@tig
tig
opened on Aug 22, 2026

Summary

Ship v2.5.0 as the next stable release: everything currently on develop (including #5416), with an explicit minor bump so this is not published as 2.4.18.

GitVersion on both main and develop is increment: Patch. A blank Prepare Release will still tag v2.4.18. Use Version override = 2.5.0.

Shipped: v2.5.0-beta.1 (2026-09-03), then stable v2.5.0 (2026-09-11) via #5673. Back-merge #5674 open.

Why 2.5.0 (not 2.4.18, not 3.0.0)

Option Verdict
2.5.0 Recommended. Same pattern as v2.2.3 → v2.4.0. v2 is still the product generation.
2.4.18 Do not. Patch with breaking API (View.Text, IAcceptTarget, CM deletion).
3.0.0 Only if we want to honor Terminal.Gui/README.md literally (“MAJOR for breaking changes”) and start treating 2.x as frozen. Bigger product statement than 2.4.0 was.

#5411 (MEC shims, [Obsolete]) already shipped in v2.4.17. 2.5.0 is the hard-removal / remaining-breaks train.

Beta vs stable: beta first — v2.5.0-beta.1 is live. Stable cut is the remaining user decision after soak.

Current state (2026-09-11)

Surface State
Latest stable v2.5.0 on main / GitHub Release (2026-09-11 ~6:18am MT). NuGet push succeeded (indexing may lag).
Previous prerelease v2.5.0-beta.1 (2026-09-03)
Release PR #5673 merged ece73d25 (merge commit)
Back-merge #5674 open (main → develop)
#5416 / #5656 Merged earlier on the train
Ecosystem All 10 canaries had validated on 2.5.0-beta.1; bump to stable 2.5.0 is follow-up

Breaking changes in 2.5.0

On develop / in v2.5.0-beta.1

PR What broke Consumer action
#5371 (fixes #5366) View.Text is non-virtual; CWP TextChanging / OnTextChanging(string) / OnTextChanged() Replace override of Text with CWP overrides; TextField no longer hides Text with new
#5395 (fixes #5369) IAcceptTarget moved to Terminal.Gui.Input Fix usings
#5416 (fixes #4367) Deletes legacy ConfigurationManager / [ConfigurationProperty] / scope types that #5411 only marked [Obsolete]; nested config.json only Migrate to TuiConfigurationBuilder + Settings POCOs; run Tools/MigrateConfig on custom config.json

Notable non-breaking already on develop

Leave other open drafts out unless they merge first: #5606, #5456.

Workstream 1 — Finish #5416 (gate) — DONE

Workstream 2 — Version bump on develop — DONE except stable override

GitVersion keeps increment: Patch on develop. #5656 landed +semver: minor (commit/PR title/merge message all minor-only; do not also put +semver: major in the message — GitVersion 6 major regex wins).

  • Land a develop commit whose message contains +semver: minor (Addresses #5630. Bump next version to 2.5.0 for breaking API +semver: minor #5656 / 3b848938)
  • Confirm subsequent develop NuGet packages are 2.5.0-develop.N (2.5.0-develop.55 … .58 on nuget.org)
  • Beta Prepare Release used Version override = 2.5.0 → v2.5.0-beta.1
  • At stable release time, Prepare Release Version override = 2.5.0 again. Do not leave it blank
  • Do not add a permanent next-version: 2.5.0 to GitVersion.yml (the tag is the source of truth after release)

Note: Terminal.Gui/README.md says develop increments Minor, but GitVersion.yml actually increments Patch. Out of scope unless we want to fix it here; +semver: minor + version override are enough for 2.5.0.

Workstream 3 — Docs before the tag — DONE

Landed with #5416 unless noted.

  • Rewrite docfx/docs/config.md around TuiConfigurationBuilder, Settings POCOs, nested JSON, Tools/MigrateConfig
  • Update docfx/docs/newinv2.md (MEC samples; points leftover CM at migrate-cm-to-mec.md)
  • Update docfx/docs/migratingfromv1.md (point v1 CM users at MEC) — PR #5658 merged
  • Add a short 2.5.0 breaking-changes section (View.Text CWP, IAcceptTarget namespace, CM deletion, config.json shape) — PR #5658 (docfx/docs/breaking-changes-2.5.0.md) merged
  • Confirm Terminal.Gui/README.md versioning table vs what we actually ship — PR #5658 merged (table now Patch + +semver: minor note)
  • No remaining ConfigurationManager.Enable calls in UICatalog / examples (leftover mentions are specs + migrate table)
  • docfx/docs/migrate-cm-to-mec.md exists

API docs deploy from develop via api-docs.yml. Docs leftovers closed in #5658 before the beta tag.

Workstream 4 — Ecosystem validation (gate) — DONE

All dependents validated and merged against public Terminal.Gui 2.5.0-beta.1 (after earlier canaries on 2.5.0-develop.55 / winprint on .57).

Dependent tui-cs repos: Editor, cli, Terminal.Gui.templates, PSTui, TerminalGuiDesigner, Examples, ai, clet, mdv. Plus tig/winprint. Not TG-dependent: tuirec, VTTest, F7History, NStack.

Per-repo checklist (all done):

  • Bump Terminal.Gui to public 2.5.0-beta.1 from nuget.org
  • Build clean, tests green (or no CI where the repo has none)
  • Fix 2.5.0 breaks as encountered (View.Text CWP, IAcceptTarget namespace, CM deletion)
  • PR opened, DO NOT MERGE warning removed after public pin, merged
Repo PR Result
Editor #287 merged
cli #43 merged
Terminal.Gui.templates #39 merged
PSTui #30 merged
TerminalGuiDesigner #326 merged
Examples #4 merged
ai #3 merged
clet #202 merged
mdv #7 merged
winprint #272 merged (incl. AOT after #5659)

tig/winprint specifics:

  • Bump to 2.5.0-beta.1 (via 2.5.0-develop.57 for AOT proof, then public beta)
  • Replace ConfigurationManager.Enable with TuiConfigurationBuilder, preserving config locations
  • Build + tests green (WinPrint.TUI.UnitTests, WinPrint.TUI.UITests); five AOT publishes green
  • Theming from ./.tui/wp.config.json preserved in the port

Docs follow-up: ai-v2-primer.md / llms.txt Schemes.Resolve row — done in #5658 (SchemeManager.GetScheme; Schemes has no Resolve).

Issue tracker — close (or decide) before Prepare Release

Gate-found regressions:

Train regressions:

Release tasks:

Verify-and-close after #5416 merges:

Decide (gate or explicitly defer to 2.6):

  • V2 has severe performance regressions #5323 — v2 performance regressions — deferred to later 2.x (not a 2.5.0 gate). Performance Gate still red on ThemeSwitch on recent heads; not a merge blocker for beta/stable of this train. Behavior notes still worth documenting later: unknown "Theme" now silently ignored (CM threw); text-field cursor now underline; Popover now a screen-filling transparent overlay; ANSI driver sizes asynchronously; Selector pads fixed-width labels; M.E.Configuration floor 10.0.11 → NU1605.

Workstream 5 — Release execution — BETA DONE; STABLE SHIPPED 2026-09-11

Follow CONTRIBUTING.md Release Process. Do not tag by hand. Prepare Release always checks out develop.

Pre-flight

Prepare Release — beta (DONE 2026-09-03)

Input Value used
Release type beta
Version override 2.5.0
  • Release PR opened into main: PR #5660 (release/v2.5.0-beta.1)
  • Required CI green on that PR
  • Title/tag is v2.5.0-beta.1, not v2.4.18
  • GitVersion.yml main label set to beta
  • Merged with a merge commit (not squash); Finalize keyed off release/

After Finalize — beta (DONE)

Prepare Release — stable (DONE 2026-09-11)

Soak v2.5.0-beta.1, then:

Input Value
Release type stable
Version override 2.5.0 (required; never blank)
  • Release PR opened into main: PR #5673 (release/v2.5.0)
  • CI green on that PR
  • Title/tag is v2.5.0, not v2.4.18 / not another beta
  • GitVersion.yml main label is '' (stable)
  • Merged with a merge commit (not squash): ece73d25 (2026-09-11 ~6:17am MT)
  • Annotated tag v2.5.0 exists
  • GitHub Release exists (stable); breaking changes at the top
  • NuGet.org push succeeded for Terminal.Gui and Terminal.Gui.Interop.Spectre 2.5.0 (workflow 34598229813; package page may lag a few minutes)
  • Back-merge PR opened: PR #5674 (main → develop) — merge when CI green
  • Closing this issue — stable cut complete; NuGet publish in flight / confirm on nuget.org

GitHub Release notes (paste at top after finalize)

Already applied on v2.5.0-beta.1. Reuse for stable:

## Breaking changes

This is a minor bump because v2 still accepts planned API breaks. Apps that compiled against 2.4.17 may need source changes.

1. **`View.Text` is no longer virtual** (#5371 / #5366)
   - Use `OnTextChanging(string proposedValue)` / `TextChanging` to validate or cancel.
   - Use `OnTextChanged()` for post-change sync.
   - `TextField` uses `View.Text` directly (no `new` hider).

2. **`IAcceptTarget` moved to `Terminal.Gui.Input`** (#5395 / #5369)
   - Add `using Terminal.Gui.Input;`.

3. **Legacy `ConfigurationManager` removed** (#5416 / #4367)
   - Replacement: `TuiConfigurationBuilder` and Settings POCOs (`ButtonSettings.Current`, etc.).
   - `config.json` is nested only. Convert old flat-key files with `Tools/MigrateConfig`.
   - Types marked `[Obsolete]` in 2.4.17 (#5411) are gone.

See the configuration deep dive and the 2.5.0 migration notes.

## Highlights

- Editable NumericUpDown
- TableView horizontal scrolling for wide content
- Native ANSI size detection; platform detection cleanup
- SynchronizationContext fix
- Kitty protocol: preserve repeated legacy input after detection
- DropDownList: hide active popover on DeRegister (#5635)
- NativeAOT: RuneJsonConverter no longer trips IL2026 (#5659)

Sequence — DONE

v2.5.0-beta.1 → soak → Prepare Release stable → #5673 merge → tag v2.5.0 + GitHub Release → NuGet + #5674 back-merge → close #5630

Out of scope

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

breaking-changeFor PRs that introduces a breaking change (behavior or API)build-and-deployIssues regarding to building and deploying Terminal.GuidocsCan be resolved via a documentation updatev2

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions