Skip to content

Commit 1351123

Browse files
CopilotmeziantouCopilot
authored
Add comprehensive GitHub Copilot instructions for wl-extensions-mediatr repository (#124)
* Initial plan * Create comprehensive GitHub Copilot instructions with validated commands Co-authored-by: meziantou <509220+meziantou@users.noreply.github.com> * Update copilot-instructions.md * Update .github/copilot-instructions.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update .github/copilot-instructions.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: meziantou <509220+meziantou@users.noreply.github.com> Co-authored-by: Gérald Barré <meziantou@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent ca23033 commit 1351123

File tree

1 file changed

+134
-0
lines changed

1 file changed

+134
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Workleap.Extensions.MediatR
2+
3+
Workleap.Extensions.MediatR is a .NET library that provides MediatR extensions, behaviors, and Roslyn analyzers for CQRS conventions. The library targets netstandard2.0 and net8.0 with additional ApplicationInsights integration.
4+
5+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
6+
7+
## Working Effectively
8+
9+
- **Install Required .NET SDK**: Download and install .NET 9.0.304 exactly as specified in global.json:
10+
- `wget https://dot.net/v1/dotnet-install.sh -O /tmp/dotnet-install.sh && chmod +x /tmp/dotnet-install.sh`
11+
- `/tmp/dotnet-install.sh --version 9.0.304 --install-dir ~/.dotnet`
12+
- `export PATH="$HOME/.dotnet:$PATH"`
13+
- **Install .NET 8.0 Runtime** (required for running tests):
14+
- `/tmp/dotnet-install.sh --version 8.0.8 --runtime dotnet --install-dir ~/.dotnet`
15+
- **Build the project**:
16+
- Navigate to `src/` directory: `cd src`
17+
- First restore: `dotnet restore` -- takes 50 seconds initially, 2 seconds subsequently. NEVER CANCEL. Set timeout to 30+ minutes.
18+
- Debug build: `dotnet build -c Debug` -- takes 9 seconds after restore. NEVER CANCEL. Set timeout to 30+ minutes.
19+
- Release build may fail with GitVersion issues in non-CI environments. Use Debug build for development.
20+
- **Run tests**:
21+
- `dotnet test -c Debug --no-build --verbosity normal` -- takes ~8 seconds if already built, ~17 seconds if a build is required. NEVER CANCEL. Set timeout to 30+ minutes.
22+
- All 86 tests should pass when environment is properly configured.
23+
- **Alternative: Use PowerShell build script** (may fail with GitVersion in non-CI):
24+
- `pwsh ./Build.ps1` -- runs clean, build, test, pack sequence
25+
26+
## Validation
27+
28+
- **ALWAYS run through complete build and test cycle** after making changes to validate functionality.
29+
- **ALWAYS run both main library tests and analyzer tests** to ensure Roslyn analyzers work correctly.
30+
- **ALWAYS test MediatR extension functionality** by checking that the library properly registers with dependency injection.
31+
- **NEVER make changes to PublicAPI.Shipped.txt** without understanding the breaking change implications.
32+
- Add new public APIs to `PublicAPI.Unshipped.txt` files in the respective project directories.
33+
- **Always check that all tests pass** - the test suite includes comprehensive validation of MediatR behaviors, analyzers, and integration scenarios.
34+
- **Validation Scenarios**: After making changes, run these end-to-end validation steps:
35+
1. `cd src && dotnet clean && dotnet restore && dotnet build -c Debug`
36+
2. `dotnet test -c Debug --no-build --verbosity normal`
37+
3. Verify all 86 tests pass
38+
4. Check that no new analyzer warnings are introduced
39+
5. Ensure PublicAPI files are updated if needed
40+
41+
## Common Tasks
42+
43+
The following are outputs from frequently run commands. Reference them instead of viewing, searching, or running bash commands to save time.
44+
45+
### Repository Structure
46+
```
47+
.
48+
├── .github/ # GitHub workflows and templates
49+
├── src/ # All source code
50+
│ ├── Workleap.Extensions.MediatR/ # Main library
51+
│ ├── Workleap.Extensions.MediatR.ApplicationInsights/ # ApplicationInsights integration
52+
│ ├── Workleap.Extensions.MediatR.Analyzers/ # Roslyn analyzers
53+
│ ├── Workleap.Extensions.MediatR.Tests/ # Main library tests
54+
│ ├── Workleap.Extensions.MediatR.Analyzers.Tests/ # Analyzer tests
55+
│ └── Workleap.Extensions.MediatR.sln # Solution file
56+
├── Build.ps1 # Main build script
57+
├── README.md # Project documentation
58+
├── global.json # .NET SDK version requirement (9.0.304)
59+
└── Directory.Build.props # Shared MSBuild properties
60+
```
61+
62+
### Key Project Components
63+
64+
1. **Main Library** (`Workleap.Extensions.MediatR`):
65+
- Multi-targets: netstandard2.0, net8.0
66+
- Provides MediatR extensions and behaviors
67+
- Includes activity-based OpenTelemetry instrumentation
68+
- High-performance logging with Debug level
69+
- Data annotations support for request validation
70+
71+
2. **ApplicationInsights Integration** (`Workleap.Extensions.MediatR.ApplicationInsights`):
72+
- Separate NuGet package for Application Insights instrumentation
73+
- Multi-targets: netstandard2.0, net8.0
74+
75+
3. **Roslyn Analyzers** (`Workleap.Extensions.MediatR.Analyzers`):
76+
- Enforces CQRS naming conventions (GMDTR01-GMDTR13 rules)
77+
- Embedded into main package during build
78+
- Validates handler design patterns
79+
80+
### Common Build Commands
81+
```bash
82+
# First restore (one-time setup - takes ~50 seconds)
83+
cd src && dotnet restore
84+
85+
# Subsequent restores (takes ~2 seconds)
86+
cd src && dotnet restore
87+
88+
# Debug build (development recommended - takes ~9 seconds)
89+
cd src && dotnet build -c Debug
90+
91+
# Run all tests (takes ~8 seconds if already built, ~17 seconds with build)
92+
cd src && dotnet test -c Debug --no-build --verbosity normal
93+
94+
# Run tests with automatic build (if you want to skip separate build step)
95+
cd src && dotnet test -c Debug --verbosity normal
96+
97+
# Clean and rebuild (for troubleshooting)
98+
cd src && dotnet clean && dotnet build -c Debug
99+
100+
# Check .NET version
101+
dotnet --version
102+
```
103+
104+
### PublicAPI Files
105+
- `PublicAPI.Shipped.txt` - Contains all shipped public APIs (DO NOT MODIFY)
106+
- `PublicAPI.Unshipped.txt` - Add new public APIs here before shipping
107+
108+
### Analyzer Rules (GMDTR01-GMDTR13)
109+
- GMDTR01-GMDTR06: Naming conventions for commands, queries, handlers, notifications
110+
- GMDTR07-GMDTR13: Design patterns and best practices
111+
112+
## Important Notes
113+
114+
- **Release builds require GitVersion** which only works in CI environments with proper git context
115+
- **Use Debug builds for local development** to avoid GitVersion issues
116+
- **PowerShell 7.4+ is available** for running Build.ps1 if needed
117+
- **Assembly signing is enabled** with Workleap.Extensions.MediatR.snk
118+
- **InternalsVisibleTo** is configured between projects for testing
119+
- **CI/CD is fully automated** - preview packages on main branch commits, stable releases on tags
120+
121+
## Project Dependencies
122+
123+
Key NuGet packages:
124+
- MediatR 12.5.0
125+
- Microsoft.Extensions.Logging.Abstractions 8.0.0
126+
- Microsoft.CodeAnalysis.PublicApiAnalyzers 3.3.4
127+
- Workleap.DotNet.CodingStandards 1.1.3 (for style and analysis)
128+
129+
## Troubleshooting
130+
131+
- **"GitVersion failed"**: Use Debug build configuration instead of Release
132+
- **"Framework not found"**: Install .NET 8.0 runtime for test execution
133+
- **"Assembly not found"**: Run `dotnet restore` in src/ directory first
134+
- **Tests failing**: Ensure both .NET 9.0.304 SDK and 8.0.8 runtime are installed

0 commit comments

Comments
 (0)