# 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](../CONTRIBUTING.md#repository-structure).

## Getting Started

For instructions on how to start using **Terminal.Gui**, refer to the [Getting Started Guide](https://gui-cs.github.io/Terminal.Gui/docs/getting-started.html) in our documentation.

## Documentation

Comprehensive documentation is available at [gui-cs.github.io/Terminal.Gui](https://gui-cs.github.io/Terminal.Gui).

For information on generating and updating the API documentation locally, refer to the [DocFX README](../docfx/README.md).

## Versioning

Version information for Terminal.Gui is managed by [gitversion](https://gitversion.net). To install `gitversion`:

```powershell
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](https://semver.org/) rules.

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

```powershell
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](https://semver.org/) 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".
	```powershell
	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`**:
	```powershell
	git checkout v2_develop
	git pull upstream v2_develop
	```

5. **Merge `v2_develop` into `v2_release`**:
	```powershell
	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`**:
	```powershell
	git tag vX.Y.Z -a -m "Release vX.Y.Z"
	```

7. **Push the new tag to `v2_release` on `upstream`**:
	```powershell
	git push --atomic upstream v2_release vX.Y.Z
	```

8. **Monitor Github Actions to ensure the NuGet publishing worked**:
	- Check [GitHub Actions](https://github.com/gui-cs/Terminal.Gui/actions).

9. **Check NuGet to see the new package version (wait a few minutes)**:
	- Visit [NuGet Package](https://www.nuget.org/packages/Terminal.Gui).

10. **Add a new Release in Github**:
	- Go to [GitHub Releases](https://github.com/gui-cs/Terminal.Gui/releases) and generate release notes with the list of PRs since the last release.

11. **Update the `v2_develop` branch with the new version**:
	```powershell
	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](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](../CONTRIBUTING.md) in the repository root.