Git_Mirror/Terminal.Gui
1
0
Fork 0
mirror of https://github.com/gui-cs/Terminal.Gui.git synced 2025-12-26 15:57:56 +01:00
Code Issues Packages Projects Releases Wiki Activity

Fixes #4332 - Refactor test infrastructure to use modern ApplicationImpl.Coordinator instead of legacy MainLoop (#4335)

Browse Source 
* Initial plan

* Refactor tests to use modern ApplicationImpl.Coordinator architecture instead of legacy Application.RunIteration

Co-authored-by: tig <585482+tig@users.noreply.github.com>

* Changes before error encountered

Co-authored-by: tig <585482+tig@users.noreply.github.com>

* Replace Application.RunIteration implementation to use modern ApplicationImpl.Coordinator architecture

Co-authored-by: tig <585482+tig@users.noreply.github.com>

* Simplify Application.RunIteration to directly delegate to ApplicationImpl.Coordinator without legacy infrastructure

Co-authored-by: tig <585482+tig@users.noreply.github.com>

* Update multitasking.md documentation to use Application.AddTimeout/RemoveTimeout instead of deprecated Application.MainLoop methods

Co-authored-by: tig <585482+tig@users.noreply.github.com>

* Refactor contribution guidelines and documentation

- Consolidated all contribution-related instructions into `CONTRIBUTING.md` as the single source of truth.
- Updated `copilot-instructions.md` and `AGENTS.md` to reference `CONTRIBUTING.md`.
- Enhanced build, test, and CI/CD workflow documentation.
- Updated repository structure documentation in `README.md` and `CONTRIBUTING.md`.
- Reinforced coding conventions and streamlined testing requirements.
- Documented GitHub Actions workflows and provided local CI replication steps.
- Refined API documentation requirements and PR guidelines.
- Simplified `.sln` file and removed redundant content.
- Updated links to point to the latest documentation resources.

* Revamp bug report template for clarity and detail

Updated the bug report template to improve structure, readability, and comprehensiveness:
- Specified "Terminal.Gui" in the `about` section.
- Replaced bold headings with Markdown heading syntax.
- Enhanced "To Reproduce" with placeholders for code and behavior details.
- Added an "Environment" section to collect OS, terminal, PowerShell, .NET, and `Terminal.Gui` version details.
- Expanded "Screenshots" to include GIFs and terminal output instructions.
- Removed outdated "Desktop" and "Smartphone" sections, consolidating relevant details.
- Improved "Additional Context" with prompts for consistency, prior behavior, and error messages.
- Streamlined "For Maintainers" instructions for setting project and milestone.

These changes aim to make bug reports more actionable and easier to reproduce.

* Remove [Obsolete] attribute and pragma warnings from Application.RunIteration - method now uses modern architecture internally

Co-authored-by: tig <585482+tig@users.noreply.github.com>

* Refactor Application.Run.cs for clarity and cleanup

Removed debug assertions and unused/commented-out code to simplify logic and improve maintainability. Renamed `forceDraw` to `forceRedraw` in `LayoutAndDraw` for better clarity. Removed the internal `OnNotifyStopRunState` method and its associated logic, indicating a refactor of the stop notification mechanism.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Tig <tig@users.noreply.github.com>
Co-authored-by: tig <585482+tig@users.noreply.github.com>
This commit is contained in:
Copilot
2025-10-26 09:15:46 -06:00
committed by GitHub
parent 1046b47be7
commit aef88ad4bb
17 changed files with 570 additions and 912 deletions
Download Patch File Download Diff File Expand all files Collapse all files

185
AGENTS.md
View File

@@ -1,179 +1,14 @@
# Terminal.Gui - GitHub Copilot Instructions
# Terminal.Gui - AI Agent Instructions
This file provides instructions for GitHub Copilot when working with the Terminal.Gui project.
> **📘 For complete contributor guidelines (humans and AI agents), see [CONTRIBUTING.md](CONTRIBUTING.md).**
## Project Overview
This repository uses [CONTRIBUTING.md](CONTRIBUTING.md) as the single source of truth for code style, testing, CI/CD, and contribution workflow. GitHub Copilot and other AI coding agents should also refer to [.github/copilot-instructions.md](.github/copilot-instructions.md) for a curated summary of non-negotiable rules.
**Terminal.Gui** is a cross-platform UI toolkit for creating console-based graphical user interfaces in .NET. It provides a comprehensive framework for building interactive console applications with support for keyboard and mouse input, customizable views, and a robust event system. The toolkit works across Windows, macOS, and Linux, leveraging platform-specific console capabilities where available.
**Key characteristics:**
- Cross-platform terminal/console UI framework for .NET
- Supports Windows, macOS, and Linux
- Rich GUI controls (buttons, dialogs, menus, text boxes, etc.)
- Keyboard-first design with full mouse support
- Follows Microsoft .NET Framework Design Guidelines, with some tweaks.
- v2 is currently in Alpha with stable core API (v1 is in maintenance mode)
## Documentation
- Full documentation: [gui-cs.github.io/Terminal.Gui](https://gui-cs.github.io/Terminal.Gui)
- API Reference: [API Documentation](https://gui-cs.github.io/Terminal.Gui/api/Terminal.Gui.App.html)
- Getting Started: [Getting Started Guide](https://gui-cs.github.io/Terminal.Gui/docs/getting-started)
## Repository Structure
- `/Terminal.Gui/` - Core library source code
- `App/` - Core application logic, `Application.cs` (static class managing `RunState` and `MainLoop`)
- `Configuration/` - `ConfigurationManager` for application settings
- `Drivers/` - Console driver implementations (`IConsoleDriver.cs`, `NetDriver`, `UnixDriver`, `WindowsDriver`)
- `Drawing/` - Rendering graphical elements in the console
- `Input/` - Keyboard and mouse input handling
- `View/` - Core `View` class hierarchy
- `Views/` - Specific sub-classes of `View` (Toplevel, Window, Dialog, etc.)
- `/Examples/` - Sample applications and demos
- `/Examples/UICatalog/` - Comprehensive demo app for manual testing
- `/Tests/` - Unit and integration tests
- `/docfx/` - Documentation source files (Deep Dive Articles and API docs)
- `/Scripts/` - Build and utility scripts
## Branching Model
**Terminal.Gui uses GitFlow:**
- `v2_develop` - Default branch for v2 development (active development)
- `v2_release` - Stable release branches matching NuGet packages
## Code Style and Standards
### Code Style Tenets
1. **Six-Year-Old Reading Level** - Prioritize readability over terseness. Use clear variable names and comments.
2. **Consistency, Consistency, Consistency** - Follow established patterns ruthlessly.
3. **Don't be Weird** - Follow Microsoft and .NET community conventions.
4. **Set and Forget** - Use ReSharper/Rider for automated formatting.
5. **Documentation is the Spec** - API documentation is the source of truth.
### Coding Conventions
- Based on [Microsoft C# Coding Conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions)
- Project settings defined and enforced via `./Terminal.sln.DotSettings` and `./.editorconfig`
- Use `var` only for the most basic dotnet types - prefer explicit types for clarity
- Use target-typed new
## API Design Guidelines
### Public API Tenets
1. **Stand on the shoulders of giants** - Follow [Microsoft .NET Framework Design Guidelines](https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/)
2. **Don't Break Existing Stuff** - Avoid breaking changes; find compatible ways to add features
3. **Fail-fast** - Prefer early failure to expose bugs sooner
4. **Standards Reduce Complexity** - Use standard .NET idioms, tweaked to match Terminal.Gui.
### API Documentation Requirements
**All public APIs must have XML documentation:**
- Clear, concise, and complete `<summary>` tags
- Use `<see cref=""/>` liberally for cross-references
- Add `<remarks>` for context and detailed explanations
- Document complex topics in `docfx/articles/*.md` files
- Use proper English and correct grammar
- Provide sample code via `<example>` in cases where a sample is needed (not for very obvious things)
### Events
- Follow the [Events Deep Dive](https://gui-cs.github.io/Terminal.Gui/docs/events.html) documentation
- Use the Cancellable Work Pattern for user-initiated actions
- Use the CWPHelpers if possible
- Name event handlers consistently (e.g., `On[EventName]`), following dotnet guidelines.
## User Experience Tenets
1. **Honor What's Come Before** - Follow established Mac/Windows GUI idioms (e.g., `Ctrl-C` for copy)
2. **Consistency Matters** - Common UI patterns should be consistent (e.g., `Ctrl-Q` quits modals)
3. **Honor the OS, but Work Everywhere** - Take advantage of platform capabilities while maintaining cross-platform support
4. **Keyboard first, Mouse also** - Optimize for keyboard, but ensure everything also works with mouse
## Testing
### Unit Test Requirements
- **Never decrease code coverage** - Aim for 70%+ coverage on new code
- Write unit tests for all new functionality
- Follow existing test patterns in `/Tests/`
- Many existing unit tests are obtuse and not really unit tests. Anytime new tests are added or updated, strive to refactor the tests into more granular tests where each test covers the smallest area possible.
- Many existing unit tests in the `./Tests/UnitTests` project incorrectly require `Application.Init` and use `[AutoInitShutdown]`. Anytime new tests are added or updated, strive to remove these dependencies and make the tests parallelizable. This means not taking any dependency on static objects like `Application` and `ConfigurationManager`.
## Pull Request Guidelines
- Titles should be of the form "Fixes #issue. Terse description."
- If the PR addresses multiple issues, use "Fixes #issue1, #issue2. Terse description."
- First comment should include "- Fixes #issue" for each issue addressed. If an issue is only partially addressed, use "Partially addresses #issue".
- First comment should include a thorough description of the change and any impact.
- Put temporary .md files in `/docfx/docs/drafts/` and remove before merging.
## Building and Running
### Build the Solution
```powershell
dotnet build
```
### Run Tests
```powershell
dotnet test
```
## Key Concepts
`./docfx/docs` contains a set of architectural and key-concept deep-dives.
## Additional Guidelines
1. Maintain existing code structure and organization unless explicitly told
2. View sub-classes must not use private APIs
3. Suggest changes to the `./docfx/docs/` folder when appropriate
## Working with Pull Request Branches
When creating PRs, include instructions at the end of each PR description for how to pull the branch down locally. Use the following template, adapted for the typical remote setup where `origin` points to the user's fork and `upstream` points to `gui-cs/Terminal.Gui`:
```markdown
## How to Pull This PR Branch Locally
If you want to test or modify this PR locally, use one of these approaches based on your remote setup:
### Method 1: Fetch from upstream (if branch exists there)
```bash
# Fetch the branch from upstream
git fetch upstream <branch-name>
# Switch to the branch
git checkout <branch-name>
# Make your changes, then commit them
git add .
git commit -m "Your commit message"
# Push to your fork (origin)
git push origin <branch-name>
```
### Method 2: Fetch by PR number
```bash
# Fetch the PR branch from upstream by PR number
git fetch upstream pull/<PR_NUMBER>/head:<branch-name>
# Switch to the branch
git checkout <branch-name>
# Make your changes, then commit them
git add .
git commit -m "Your commit message"
# Push to your fork (origin)
git push origin <branch-name>
```
The PR will automatically update when you push to the branch in your fork.
```
**Note:** Adjust the remote names if your setup differs (e.g., if `origin` points to `gui-cs/Terminal.Gui` and you have a separate remote for your fork).
**Key highlights for AI agents:**
- Always use explicit types (no `var` except for built-in simple types)
- Always use target-typed `new()` syntax
- Add new tests to `Tests/UnitTestsParallelizable/` when possible
- Never decrease code coverage
- Follow `.editorconfig` and `Terminal.sln.DotSettings` for formatting
See [CONTRIBUTING.md](CONTRIBUTING.md) for complete details.