Skip to content

Commit 11bcb01

Browse files
CopilotGcaya
Copilot
and
Gcaya
authored
Add comprehensive GitHub Copilot instructions for development workflow (#123)
* Initial plan * Initial plan for Copilot instructions Co-authored-by: Gcaya <8711024+Gcaya@users.noreply.github.com> * Add comprehensive GitHub Copilot instructions Co-authored-by: Gcaya <8711024+Gcaya@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Gcaya <8711024+Gcaya@users.noreply.github.com>
1 parent 8df79a2 commit 11bcb01

File tree

1 file changed

+191
-0
lines changed

1 file changed

+191
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Workleap.DotNet.CodingStandards
2+
3+
**ALWAYS follow these instructions first and only fallback to additional search and context gathering if the information in the instructions is incomplete or found to be in error.**
4+
5+
Workleap.DotNet.CodingStandards is a NuGet package that provides coding standards, analyzers, and .editorconfig files for .NET projects. It packages MSBuild properties/targets files and generated analyzer configuration files.
6+
7+
## Working Effectively
8+
9+
### Bootstrap, Build, and Test the Repository
10+
**CRITICAL TIMING:** Build takes 60+ seconds. Tests take 32+ seconds. ConfigurationFilesGenerator takes 15+ seconds. NEVER CANCEL any of these operations.
11+
12+
1. **Install required dependencies:**
13+
```bash
14+
# Install .NET 9.0 SDK (required by global.json)
15+
wget https://dotnetcli.azureedge.net/dotnet/Sdk/9.0.304/dotnet-sdk-9.0.304-linux-x64.tar.gz
16+
sudo mkdir -p /usr/share/dotnet9
17+
sudo tar zxf dotnet-sdk-9.0.304-linux-x64.tar.gz -C /usr/share/dotnet9
18+
export PATH="/usr/share/dotnet9:$PATH"
19+
export DOTNET_ROOT="/usr/share/dotnet9"
20+
21+
# Install .NET 8.0 runtime (required for tests)
22+
wget https://dotnetcli.azureedge.net/dotnet/Runtime/8.0.12/dotnet-runtime-8.0.12-linux-x64.tar.gz
23+
sudo tar zxf dotnet-runtime-8.0.12-linux-x64.tar.gz -C /usr/share/dotnet9
24+
25+
# Install Mono and NuGet.exe (required for packaging and tests)
26+
sudo apt-get install -y mono-complete
27+
wget https://dist.nuget.org/win-x86-commandline/latest/nuget.exe
28+
sudo mv nuget.exe /usr/local/bin/
29+
echo '#!/bin/bash
30+
exec mono /usr/local/bin/nuget.exe "$@"' | sudo tee /usr/local/bin/nuget
31+
sudo chmod +x /usr/local/bin/nuget
32+
33+
# Install PowerShell (if not available)
34+
# PowerShell is already available in GitHub Actions
35+
```
36+
37+
2. **Restore tools and build components:**
38+
```bash
39+
dotnet tool restore # Installs GitVersion - takes 5 seconds
40+
41+
# Generate analyzer configuration files - takes 15 seconds. NEVER CANCEL.
42+
dotnet run --project=tools/ConfigurationFilesGenerator/ConfigurationFilesGenerator.csproj --configuration Release --verbosity normal
43+
```
44+
45+
3. **Run tests - takes 35 seconds. NEVER CANCEL. Set timeout to 60+ minutes:**
46+
```bash
47+
dotnet test --configuration Release --logger "console;verbosity=normal"
48+
```
49+
50+
4. **Package the NuGet package - takes 2 seconds:**
51+
```bash
52+
# Get version (may fail on feature branches - use manual version instead)
53+
VERSION=$(dotnet dotnet-gitversion /output json /showvariable SemVer 2>/dev/null || echo "1.1.25-dev")
54+
55+
# Pack the package
56+
nuget pack Workleap.DotNet.CodingStandards.nuspec -OutputDirectory .output -Version $VERSION -ForceEnglishOutput
57+
```
58+
59+
5. **Complete build script (mimics Build.ps1):**
60+
```bash
61+
# NEVER CANCEL: Full build takes 60+ seconds
62+
export PATH="/usr/share/dotnet9:/usr/local/bin:$PATH"
63+
export DOTNET_ROOT="/usr/share/dotnet9"
64+
65+
dotnet tool restore
66+
dotnet run --project=tools/ConfigurationFilesGenerator/ConfigurationFilesGenerator.csproj --configuration Release
67+
VERSION=$(dotnet dotnet-gitversion /output json /showvariable SemVer 2>/dev/null || echo "1.1.25-dev")
68+
nuget pack Workleap.DotNet.CodingStandards.nuspec -OutputDirectory .output -Version $VERSION -ForceEnglishOutput
69+
dotnet test --configuration Release --logger "console;verbosity=normal"
70+
```
71+
72+
### Environment Setup Commands
73+
These are the exact commands for setting up the development environment:
74+
75+
```bash
76+
# Set environment variables for all operations
77+
export PATH="/usr/share/dotnet9:/usr/local/bin:$PATH"
78+
export DOTNET_ROOT="/usr/share/dotnet9"
79+
80+
# Verify installation
81+
dotnet --version # Should show 9.0.304
82+
nuget # Should show NuGet command line help
83+
pwsh --version # Should show PowerShell 7.x
84+
```
85+
86+
## Validation
87+
88+
### Manual Testing Scenarios
89+
**ALWAYS run these validation steps after making changes:**
90+
91+
1. **Verify ConfigurationFilesGenerator works:**
92+
```bash
93+
# Should complete in ~15 seconds and show analyzer packages being processed
94+
dotnet run --project=tools/ConfigurationFilesGenerator/ConfigurationFilesGenerator.csproj --configuration Release
95+
96+
# Verify generated files exist
97+
ls -la src/files/analyzers/
98+
# Should show: Analyzer.*.editorconfig files and manual_rules.editorconfig
99+
```
100+
101+
2. **Verify package contents:**
102+
```bash
103+
# After packaging, check package contents
104+
unzip -l .output/Workleap.DotNet.CodingStandards.*.nupkg
105+
# Should contain: build/, buildTransitive/, buildMultiTargeting/, files/ directories
106+
```
107+
108+
3. **Test package installation (end-to-end test):**
109+
```bash
110+
# Create test project
111+
mkdir test-project && cd test-project
112+
dotnet new console
113+
dotnet add package Workleap.DotNet.CodingStandards --source ../../../.output --prerelease
114+
dotnet build
115+
# Should build successfully with coding standards applied
116+
```
117+
118+
### CI Validation Commands
119+
Always run these before committing changes:
120+
121+
```bash
122+
# These commands mirror what CI does and must pass
123+
dotnet format --verify-no-changes # Verify code formatting
124+
dotnet build --configuration Release # Verify build succeeds
125+
dotnet test --configuration Release # Verify all tests pass
126+
```
127+
128+
## Common Tasks and Troubleshooting
129+
130+
### Working with the ConfigurationFilesGenerator
131+
- **Purpose:** Downloads NuGet analyzer packages and generates corresponding .editorconfig files
132+
- **Input:** Hardcoded list of analyzer packages in Program.cs
133+
- **Output:** src/files/analyzers/Analyzer.*.editorconfig files
134+
- **Timing:** Takes 15+ seconds to download and process all analyzer packages
135+
136+
### Key Repository Locations
137+
```
138+
src/
139+
├── build/ # MSBuild .props/.targets files
140+
├── buildTransitive/ # Transitive MSBuild files
141+
├── buildMultiTargeting/ # Multi-targeting MSBuild files
142+
└── files/
143+
├── *.editorconfig # Static configuration files
144+
├── BannedSymbols.txt # Banned API definitions
145+
└── analyzers/ # Generated analyzer configs
146+
tools/
147+
└── ConfigurationFilesGenerator/ # Tool to generate analyzer configs
148+
tests/
149+
└── Workleap.DotNet.CodingStandards.Tests/ # xUnit test project
150+
```
151+
152+
### Dependencies and Requirements
153+
- **.NET 9.0 SDK:** Required for building (specified in global.json)
154+
- **.NET 8.0 Runtime:** Required for running tests (test project targets net8.0)
155+
- **PowerShell:** Required for Build.ps1 script
156+
- **Mono + NuGet.exe:** Required for packaging and test fixtures
157+
- **GitVersion:** .NET tool for automatic versioning
158+
159+
### Timing Expectations
160+
**CRITICAL: Never cancel these operations. Set timeouts appropriately:**
161+
- Tool restore: ~5 seconds
162+
- ConfigurationFilesGenerator: ~15 seconds
163+
- Full build: ~20 seconds
164+
- Tests: ~32 seconds (14 test cases)
165+
- Full CI pipeline: ~60 seconds total
166+
167+
### Build Failures and Solutions
168+
- **"SDK not found" error:** Ensure .NET 9.0 SDK is installed and in PATH
169+
- **"nuget command not found":** Install mono and create nuget wrapper script
170+
- **Test failures with runtime errors:** Ensure .NET 8.0 runtime is available
171+
- **GitVersion errors on feature branches:** Use manual version instead
172+
173+
### Package Structure
174+
The NuGet package contains:
175+
- **MSBuild integration:** Automatic import of .props/.targets files
176+
- **EditorConfig files:** Code style and analyzer rules configuration
177+
- **Banned symbols:** API usage restrictions
178+
- **Analyzer dependencies:** Meziantou.Analyzer, StyleCop.Analyzers, Microsoft analyzers
179+
180+
### Testing Strategy
181+
Tests use ProjectBuilder helper to:
182+
1. Create temporary test projects with NuGet.config
183+
2. Add the coding standards package
184+
3. Build projects and capture SARIF output
185+
4. Validate expected warnings/errors are present
186+
187+
## References
188+
- Build script: Build.ps1 (PowerShell)
189+
- CI workflow: .github/workflows/ci.yml
190+
- Package definition: Workleap.DotNet.CodingStandards.nuspec
191+
- Test project: tests/Workleap.DotNet.CodingStandards.Tests/

0 commit comments

Comments
 (0)