Terminal.Gui Library — Maintainer Guide

This directory contains the core Terminal.Gui library source code. This README documents how to maintain and release the library. For contribution guidelines, see CONTRIBUTING.md. For building apps with Terminal.Gui, see the documentation.

Versioning

Versions are computed automatically by GitVersion 6.x using the GitFlow branching strategy. Configuration is in GitVersion.yml.

The GitVersion.MsBuild NuGet package is included in Terminal.Gui.csproj and automatically sets Version, AssemblyVersion, FileVersion, and InformationalVersion from git history at build time. No manual version management is needed.

How Versions Are Computed

Checking Versions Locally

# Install the CLI tool (one-time)
dotnet tool install --global GitVersion.Tool

# Show what version would be computed for the current branch
dotnet-gitversion

The version is also embedded in every build. For example, UICatalog --version displays the terse SemVer (build metadata after + is stripped).

Pre-Release Label Progression on main

To change the pre-release stage, edit the label field under main in GitVersion.yml:

Publishing a Release

Releases follow Semantic Versioning: MAJOR for breaking changes, MINOR for new features, PATCH for bug fixes.

Automated Release Workflow (Preferred)

Two workflows handle the release lifecycle:

Step 1 — Prepare Release (manual trigger):

1. Go to Actions → Prepare Release → Run workflow.
2. Pick the release type (beta, rc, stable) and optionally override the version.
3. The workflow creates a release/vX.Y.Z branch from develop, updates the GitVersion.yml label, and opens a PR into main.
4. Review the PR — CI runs, branch protections apply.

Step 2 — Finalize Release (automatic on PR merge): When the release PR is merged into main:

1. Creates an annotated tag (vX.Y.Z or vX.Y.Z-beta)
2. Creates a GitHub Release with auto-generated notes
3. Publish fires automatically → NuGet package published
4. Opens a back-merge PR (main → develop) to keep branches in sync

Manual Release Steps

If you need to release manually:

1. Ensure develop is ready: all changes committed, CI passing.

2. Merge develop into main:

   powershellCopy

   git checkout main
   git pull upstream main
   git checkout develop
   git pull upstream develop
   git checkout main
   git merge develop
   # Fix any merge conflicts
   

3. Update the pre-release label in GitVersion.yml if changing stages (e.g., beta → rc → '').

4. Tag the release on main:

   powershellCopy

   git tag vX.Y.Z -a -m "Release vX.Y.Z"
   

5. Push atomically:

   powershellCopy

   git push --atomic upstream main vX.Y.Z
   

6. Monitor CI: the Publish workflow builds and pushes to NuGet. It also triggers an update to Terminal.Gui.templates for stable releases.

7. Create a GitHub Release at Releases with auto-generated release notes.

8. Merge main back into develop:

   powershellCopy

   git checkout develop
   git pull upstream develop
   git merge main
   git push upstream develop
   

CI/CD Workflows

All workflows are in .github/workflows/:

V1 Legacy Branches

Terminal.Gui V1 (latest: v1.19.0) is maintained on separate branches:

V1 follows the same GitFlow model as V2 but is in maintenance-only mode. The V1 NuGet package is Terminal.Gui 1.x. V1 API docs are published from v1_release to a separate GitHub Pages path.

These branches are not configured in GitVersion.yml (the config was removed to avoid interference with V2 versioning). V1 releases are tagged manually (e.g., v1.19.0).

NuGet Package

• Package: nuget.org/packages/Terminal.Gui
• Auto-published on every push to main or develop (pre-release versions from develop, stable versions from main)
• Pre-release versions (e.g., 2.1.0-develop.42) are marked as pre-release on NuGet

Local Package Development

When building in Release configuration, the .csproj automatically:

1. Copies .nupkg and .snupkg to ../local_packages/
2. Pushes the package to the local NuGet cache

Use the local_packages folder as a local NuGet source to test packages before publishing:

dotnet build Terminal.Gui/Terminal.Gui.csproj -c Release
# Package is now in local_packages/ and your global NuGet cache

Documentation

• Live docs: gui-cs.github.io/Terminal.Gui
• DocFX source: docfx/ — see docfx/README.md for local generation
• API docs are auto-deployed to GitHub Pages on every push to main

Contributing

See CONTRIBUTING.md for build/test instructions, coding conventions, and PR guidelines.