|
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/ |
| 1 | +**Any code you commit SHOULD compile, and new and existing tests related to the change SHOULD pass.** |
| 2 | + |
| 3 | +You MUST make your best effort to ensure your changes satisfy those criteria before committing. If for any reason you were unable to build or test the changes, you MUST report that. You MUST NOT claim success unless all builds and tests pass as described above. |
| 4 | + |
| 5 | +Do not complete without checking the relevant code builds and relevant tests still pass after the last edits you make. Do not simply assume that your changes fix test failures you see, actually build and run those tests again to confirm. |
| 6 | +Also, do not assume that tests pass just because you did not see any failures in your last test run; verify that all relevant tests were actually run. |
| 7 | + |
| 8 | +You MUST follow all code-formatting and naming conventions defined in [`.editorconfig`](/.editorconfig). |
| 9 | + |
| 10 | +In addition to the rules enforced by `.editorconfig`, you SHOULD: |
| 11 | + |
| 12 | +- Prefer file-scoped namespace declarations and single-line using directives. |
| 13 | +- Ensure that the final return statement of a method is on its own line. |
| 14 | +- Use pattern matching and switch expressions wherever possible. |
| 15 | +- Use `nameof` instead of string literals when referring to member names. |
| 16 | +- Always use `is null` or `is not null` instead of `== null` or `!= null`. |
| 17 | +- Trust the C# null annotations and don't add null checks when the type system says a value cannot be null. |
| 18 | +- Prefer `?.` if applicable (e.g. `scope?.Dispose()`). |
| 19 | +- Use `ObjectDisposedException.ThrowIf` where applicable. |
| 20 | +- When adding new unit tests, strongly prefer to add them to existing test code files rather than creating new code files. |
| 21 | +- When running tests, if possible use filters and check test run counts, or look at test logs, to ensure they actually ran. |
| 22 | +- Do not finish work with any tests commented out or disabled that were not previously commented out or disabled. |
| 23 | +- Do not update `global.json` file |
| 24 | +- When writing tests, do not emit "Act", "Arrange" or "Assert" comments. |
| 25 | +- There should be no trailing whitespace in any lines. |
| 26 | +- Add a blank line before XML documentation comments (`///`) when they follow other code (methods, properties, fields, etc.). |
0 commit comments