Terminal.Gui/Terminal.Gui/README.md

Terminal.Gui Project

Terminal.Gui is a cross-platform UI toolkit for creating console-based graphical user interfaces in .NET. This repository contains all files required to build the Terminal.Gui library and NuGet package, enabling developers to create rich terminal applications with ease.

Project Overview

Terminal.Gui provides a comprehensive framework for building interactive console applications with support for keyboard and mouse input, customizable views, and a robust event system. It is designed to work across Windows, macOS, and Linux, leveraging platform-specific console capabilities where available.

Project Folder Structure

This directory contains the core Terminal.Gui library source code. For a detailed repository structure, see CONTRIBUTING.md - Repository Structure.

Getting Started

For instructions on how to start using Terminal.Gui, refer to the Getting Started Guide in our documentation.

Documentation

Comprehensive documentation is available at gui-cs.github.io/Terminal.Gui.

For information on generating and updating the API documentation locally, refer to the DocFX README.

Versioning

Version information for Terminal.Gui is managed by gitversion. To install gitversion:

dotnet tool install --global GitVersion.Tool
dotnet-gitversion

The project version (used in the NuGet package and Terminal.Gui.dll) is determined from the latest git tag. The format of version numbers is major.minor.patch.build.height and follows Semantic Versioning rules.

To define a new version, tag a commit using git tag:

git tag v2.1.0-beta.1 -a -m "Release v2.1.0 Beta 1"
dotnet-gitversion /updateprojectfiles
dotnet build -c Release

DO NOT COMMIT AFTER USING /updateprojectfiles! Doing so will update the .csproj files in your branch with version info, which we do not want.

Publishing a Release of Terminal.Gui

To release a new version, follow these steps based on Semantic Versioning rules:

• MAJOR version for incompatible API changes.
• MINOR version for backwards-compatible functionality additions.
• PATCH version for backwards-compatible bug fixes.

Steps for Release:

1. Verify the v2_develop branch is ready for release:

   • Ensure all changes are committed and pushed to the v2_develop branch.
   • Ensure your local v2_develop branch is up-to-date with upstream/v2_develop.

2. Create a pull request for the release in the v2_develop branch:

   • Title the PR as "Release vX.Y.Z".

   git checkout v2_develop
   git pull upstream v2_develop
   git checkout -b vX_Y_Z
   git add .
   git commit -m "Release vX.Y.Z"
   git push
   

   • Go to the link printed by git push and fill out the Pull Request.

3. On github.com, verify the build action worked on your fork, then merge the PR.

4. Pull the merged v2_develop from upstream:

   git checkout v2_develop
   git pull upstream v2_develop
   

5. Merge v2_develop into v2_release:

   git checkout v2_release
   git pull upstream v2_release
   git merge v2_develop
   

   • Fix any merge errors.

6. Create a new annotated tag for the release on v2_release:

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

7. Push the new tag to v2_release on upstream:

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

8. Monitor Github Actions to ensure the NuGet publishing worked:

   • Check GitHub Actions.

9. Check NuGet to see the new package version (wait a few minutes):

   • Visit NuGet Package.

10. Add a new Release in Github:

    • Go to GitHub Releases and generate release notes with the list of PRs since the last release.

11. Update the v2_develop branch with the new version:

    git checkout v2_develop
    git pull upstream v2_develop
    git merge v2_release
    git push upstream v2_develop
    

NuGet

The official NuGet package for Terminal.Gui is available at https://www.nuget.org/packages/Terminal.Gui. When a new version tag is defined and merged into v2_release, a NuGet package is automatically generated by a GitHub Action. Pre-release versions (e.g., 2.0.0-beta.5) are tagged as pre-release on NuGet.

Contributing

We welcome contributions from the community. For complete contribution guidelines, including:

• Build and test instructions
• Coding conventions and style rules
• Testing requirements and patterns
• Pull request guidelines
• CI/CD workflows

Please refer to CONTRIBUTING.md in the repository root.