From 4b193ecb0d3300dc1973f223de4b98c77c28654e Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Thu, 23 Oct 2025 15:32:17 -0600 Subject: [PATCH] Add onboarding instructions for Copilot and other AI coding agents (#4314) * Initial plan * Add copilot-instructions.md and .cursorrules for AI agents Co-authored-by: tig <585482+tig@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: tig <585482+tig@users.noreply.github.com> --- .cursorrules | 48 ++++++ .github/copilot-instructions.md | 293 ++++++++++++++++++++++++++++++++ 2 files changed, 341 insertions(+) create mode 100644 .cursorrules create mode 100644 .github/copilot-instructions.md diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 000000000..48d730993 --- /dev/null +++ b/.cursorrules @@ -0,0 +1,48 @@ +# Terminal.Gui - Cursor AI Rules + +This project uses comprehensive AI agent instructions. See: +- `.github/copilot-instructions.md` - Complete onboarding guide (primary reference) +- `AGENTS.md` - General AI agent guidelines + +## Quick Reference + +### Project Type +- .NET 8.0 cross-platform console UI toolkit +- 496 source files in core library +- GitFlow branching (v2_develop = default) + +### Essential Commands + +```bash +# Always run from repo root in this order: +dotnet restore # First! (~15-20s) +dotnet build --configuration Debug --no-restore # ~50s, expect ~326 warnings +dotnet test Tests/UnitTestsParallelizable --no-build # Preferred test suite +dotnet run --project Examples/UICatalog/UICatalog.csproj # Demo app +``` + +### Code Style (Enforced) +- **DO**: Use explicit types (avoid `var`), target-typed `new()`, 4-space indent +- **DO**: Format only files you modify (ReSharper/Rider `Ctrl-E-C` or `Ctrl-K-D`) +- **DO**: Follow `.editorconfig` and `Terminal.sln.DotSettings` +- **DON'T**: Add new linters, modify unrelated code, decrease test coverage + +### Testing Rules +- Add new tests to `Tests/UnitTestsParallelizable/` (preferred) +- Avoid `Application.Init` and static dependencies in tests +- Don't use `[AutoInitShutdown]` attribute (legacy) +- Maintain 70%+ code coverage on new code + +### API Documentation (Required) +- All public APIs need XML docs (``, ``, ``) +- Use `` for cross-references +- Complex topics → `docfx/docs/*.md` + +### Common Issues +- ~326 build warnings are normal (nullable refs, etc.) +- Tests can take 5-10 minutes +- Run `dotnet restore` before any build +- Read `.github/copilot-instructions.md` for full troubleshooting + +--- +**See `.github/copilot-instructions.md` for complete instructions** diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..444ac8c4b --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,293 @@ +# Terminal.Gui - Copilot Coding Agent Instructions + +This file provides onboarding instructions for GitHub Copilot and other AI coding agents working with Terminal.Gui. + +## Project Overview + +**Terminal.Gui** is a cross-platform UI toolkit for creating console-based graphical user interfaces in .NET. It's a large codebase (~1,050 C# files, 333MB) providing a comprehensive framework for building interactive console applications with support for keyboard and mouse input, customizable views, and a robust event system. + +**Key characteristics:** +- **Language**: C# (net8.0) +- **Size**: ~496 source files in core library, ~1,050 total C# files +- **Platform**: Cross-platform (Windows, macOS, Linux) +- **Architecture**: Console UI toolkit with driver-based architecture +- **Version**: v2 (Alpha), v1 (maintenance mode) +- **Branching**: GitFlow model (v2_develop is default/active development) + +## Building and Testing + +### Required Tools +- **.NET SDK**: 8.0.0 (see `global.json`) +- **Runtime**: .NET 8.x (latest GA) +- **Optional**: ReSharper/Rider for code formatting + +### Build Commands (In Order) + +**ALWAYS run these commands from the repository root:** + +1. **Restore packages** (required first, ~15-20 seconds): + ```bash + dotnet restore + ``` + +2. **Build solution** (Debug, ~50 seconds): + ```bash + dotnet build --configuration Debug --no-restore + ``` + - Expect ~326 warnings (nullable reference warnings, unused variables, etc.) - these are normal + - 0 errors expected + +3. **Build Release** (for packaging): + ```bash + dotnet build --configuration Release --no-restore + ``` + +### Test Commands + +**Two test projects exist:** + +1. **Non-parallel tests** (depend on static state, ~10 min timeout): + ```bash + dotnet test Tests/UnitTests --no-build --verbosity normal + ``` + - Uses `Application.Init` and static state + - Cannot run in parallel + - Includes `--blame` flags for crash diagnostics + +2. **Parallel tests** (can run concurrently, ~10 min timeout): + ```bash + dotnet test Tests/UnitTestsParallelizable --no-build --verbosity normal + ``` + - No dependencies on static state + - Preferred for new tests + +3. **Integration tests**: + ```bash + dotnet test Tests/IntegrationTests --no-build --verbosity normal + ``` + +**Important**: Tests may take significant time. CI uses blame flags for crash detection: +```bash +--diag:logs/UnitTests/logs.txt --blame --blame-crash --blame-hang --blame-hang-timeout 60s --blame-crash-collect-always +``` + +### Running Examples + +**UICatalog** (comprehensive demo app): +```bash +dotnet run --project Examples/UICatalog/UICatalog.csproj +``` + +## Repository Structure + +### Root Directory Files +- `Terminal.sln` - Main solution file +- `Terminal.sln.DotSettings` - ReSharper code style settings +- `.editorconfig` - Code formatting rules (111KB, extensive) +- `global.json` - .NET SDK version pinning +- `Directory.Build.props` - Common MSBuild properties +- `Directory.Packages.props` - Central package version management +- `GitVersion.yml` - Version numbering configuration +- `AGENTS.md` - General AI agent instructions (also useful reference) +- `CONTRIBUTING.md` - Contribution guidelines +- `README.md` - Project documentation + +### Main Directories + +**`/Terminal.Gui/`** - Core library (496 C# files): +- `App/` - Application lifecycle (`Application.cs` static class, `RunState`, `MainLoop`) +- `Configuration/` - `ConfigurationManager` for settings +- `Drivers/` - Console driver implementations (`IConsoleDriver`, `NetDriver`, `UnixDriver`, `WindowsDriver`) +- `Drawing/` - Rendering system (attributes, colors, glyphs) +- `Input/` - Keyboard and mouse input handling +- `ViewBase/` - Core `View` class hierarchy and layout +- `Views/` - Specific View subclasses (Window, Dialog, Button, ListView, etc.) +- `Text/` - Text manipulation and formatting + +**`/Tests/`**: +- `UnitTests/` - Non-parallel tests (use `Application.Init`, static state) +- `UnitTestsParallelizable/` - Parallel tests (no static dependencies) +- `IntegrationTests/` - Integration tests +- `StressTests/` - Long-running stress tests (scheduled daily) +- `coverlet.runsettings` - Code coverage configuration + +**`/Examples/`**: +- `UICatalog/` - Comprehensive demo app for manual testing +- `Example/` - Basic example +- `NativeAot/`, `SelfContained/` - Deployment examples +- `ReactiveExample/`, `CommunityToolkitExample/` - Integration examples + +**`/docfx/`** - Documentation source: +- `docs/` - Conceptual documentation (deep dives) +- `api/` - Generated API docs (gitignored) +- `docfx.json` - DocFX configuration + +**`/Scripts/`** - PowerShell build utilities (requires PowerShell 7.4+) + +**`/.github/workflows/`** - CI/CD pipelines: +- `unit-tests.yml` - Main test workflow (Ubuntu, Windows, macOS) +- `build-release.yml` - Release build verification +- `integration-tests.yml` - Integration test workflow +- `publish.yml` - NuGet package publishing +- `api-docs.yml` - Documentation building and deployment +- `codeql-analysis.yml` - Security scanning + +## Code Style and Quality + +### Formatting +- **Do NOT add formatting tools** - Use existing `.editorconfig` and `Terminal.sln.DotSettings` +- Format code with: + 1. ReSharper/Rider (`Ctrl-E-C`) + 2. JetBrains CleanupCode CLI tool (free) + 3. Visual Studio (`Ctrl-K-D`) as fallback +- **Only format files you modify** + +### Code Style Tenets +1. **Six-Year-Old Reading Level** - Readability over terseness +2. **Consistency, Consistency, Consistency** - Follow existing patterns ruthlessly +3. **Don't be Weird** - Follow Microsoft/.NET conventions +4. **Set and Forget** - Rely on automated tooling +5. **Documentation is the Spec** - API docs are source of truth + +### Coding Conventions +- Use explicit types (avoid `var` except for basic types like `int`, `string`) +- Use target-typed `new()` +- Follow `.editorconfig` settings (e.g., braces on new lines, spaces after keywords) +- 4-space indentation +- See `CONTRIBUTING.md` for full guidelines + +## Testing Requirements + +### Code Coverage +- **Never decrease code coverage** - PRs must maintain or increase coverage +- Target: 70%+ coverage for new code +- CI monitors coverage on each PR + +### Test Patterns +- **Parallelizable tests preferred** - Add new tests to `UnitTestsParallelizable` when possible +- **Avoid static dependencies** - Don't use `Application.Init`, `ConfigurationManager` in tests +- **Don't use `[AutoInitShutdown]`** - Legacy pattern, being phased out +- **Make tests granular** - Each test should cover smallest area possible +- Follow existing test patterns in respective test projects + +### Test Configuration +- `xunit.runner.json` - xUnit configuration +- `coverlet.runsettings` - Coverage settings (OpenCover format) + +## API Documentation Requirements + +**All public APIs MUST have XML documentation:** +- Clear, concise `` tags +- Use `` for cross-references +- Add `` for context +- Include `` for non-obvious usage +- Complex topics → `docfx/docs/*.md` files +- Proper English and grammar + +## Common Build Issues + +### Issue: Build Warnings +- **Expected**: ~326 warnings (nullable refs, unused vars, xUnit suggestions) +- **Action**: Don't add new warnings; fix warnings in code you modify + +### Issue: Test Timeouts +- **Expected**: Tests can take 5-10 minutes +- **Action**: Use appropriate timeout values (60-120 seconds for test commands) + +### Issue: Restore Failures +- **Solution**: Ensure `dotnet restore` completes before building +- **Note**: Takes 15-20 seconds on first run + +### Issue: NativeAot/SelfContained Build +- **Solution**: Restore these projects explicitly: + ```bash + dotnet restore ./Examples/NativeAot/NativeAot.csproj -f + dotnet restore ./Examples/SelfContained/SelfContained.csproj -f + ``` + +## CI/CD Validation + +The following checks run on PRs: + +1. **Unit Tests** (`unit-tests.yml`): + - Runs on Ubuntu, Windows, macOS + - Both parallel and non-parallel test suites + - Code coverage collection + - 10-minute timeout per job + +2. **Build Release** (`build-release.yml`): + - Verifies Release configuration builds + - Tests NativeAot and SelfContained builds + - Packs NuGet package + +3. **Integration Tests** (`integration-tests.yml`): + - Cross-platform integration testing + - 10-minute timeout + +4. **CodeQL Analysis** (`codeql-analysis.yml`): + - Security vulnerability scanning + +To replicate CI locally: +```bash +# Full CI sequence: +dotnet restore +dotnet build --configuration Debug --no-restore +dotnet test Tests/UnitTests --no-build --verbosity normal +dotnet test Tests/UnitTestsParallelizable --no-build --verbosity normal +dotnet build --configuration Release --no-restore +``` + +## Branching and PRs + +### GitFlow Model +- `v2_develop` - Default branch, active development +- `v2_release` - Stable releases, matches NuGet +- `v1_develop`, `v1_release` - Legacy v1 (maintenance only) + +### PR Requirements +- **Title**: "Fixes #issue. Terse description" +- **Description**: Include "- Fixes #issue" for each issue +- **Tests**: Add tests for new functionality +- **Coverage**: Maintain or increase code coverage +- **Scenarios**: Update UICatalog scenarios when adding features + +## Key Architecture Concepts + +### View System +- `View` base class in `/Terminal.Gui/ViewBase/` +- Two layout modes: Absolute and Computed +- Event-driven architecture +- Adornments: Border, Margin, Padding + +### Console Drivers +- `IConsoleDriver` interface +- Platform-specific: `WindowsDriver`, `UnixDriver`, `NetDriver` +- `FakeDriver` for testing + +### Application Lifecycle +- `Application` static class manages lifecycle +- `MainLoop` handles event processing +- `RunState` tracks application state + +## What NOT to Do + +- ❌ Don't add new linters/formatters (use existing) +- ❌ Don't modify unrelated code +- ❌ Don't remove/edit unrelated tests +- ❌ Don't break existing functionality +- ❌ Don't add tests to `UnitTests` if they can be parallelizable +- ❌ Don't use `Application.Init` in new tests +- ❌ Don't decrease code coverage +- ❌ Don't add `var` everywhere (use explicit types) + +## Additional Resources + +- **Full Documentation**: https://gui-cs.github.io/Terminal.Gui +- **API Reference**: https://gui-cs.github.io/Terminal.Gui/api/Terminal.Gui.App.html +- **Deep Dives**: `/docfx/docs/` directory +- **AGENTS.md**: Additional AI agent instructions +- **CONTRIBUTING.md**: Detailed contribution guidelines + +--- + +**Trust these instructions.** Only search for additional information if instructions are incomplete or incorrect.