|
| 1 | +# GitHub Copilot Instructions for bUnit |
| 2 | + |
| 3 | +This document outlines the coding standards, guidelines, and best practices for contributing to the bUnit project. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +bUnit is a testing library for Blazor Components that runs on top of existing unit testing frameworks (xUnit, NUnit, MSTest, TUnit). The goal is to write comprehensive, stable unit tests that run in milliseconds. |
| 8 | + |
| 9 | +## Coding Standards |
| 10 | + |
| 11 | +### Language and Framework |
| 12 | +- **C# Language Version**: Use `preview` features as defined in `Directory.Build.props` |
| 13 | +- **Nullable Reference Types**: Always enabled - use nullable annotations appropriately |
| 14 | +- **Implicit Usings**: Enabled - common namespaces are automatically imported |
| 15 | + |
| 16 | +### Code Style (Based on .editorconfig) |
| 17 | + |
| 18 | +#### Indentation and Formatting |
| 19 | +- Use **tabs** for indentation (not spaces) |
| 20 | +- Tab width: 4 spaces |
| 21 | +- Charset: UTF-8 |
| 22 | +- Always trim trailing whitespace (except in .md files) |
| 23 | +- Insert final newline in all files |
| 24 | + |
| 25 | +#### C# Style Conventions |
| 26 | +- Use `var` for built-in types and when type is apparent |
| 27 | +- Prefer expression-bodied members for single-line methods, properties, and accessors |
| 28 | +- Use pattern matching over `as` with null check and `is` with cast check |
| 29 | +- Prefer object and collection initializers |
| 30 | +- Use language keywords instead of framework type names (e.g., `int` not `Int32`) |
| 31 | +- Always use braces for code blocks (even single-line if statements) |
| 32 | +- Prefer `null` propagation and coalesce expressions |
| 33 | +- Use file-scoped namespaces (C# 10+) |
| 34 | +- Place using directives outside namespace |
| 35 | + |
| 36 | +#### Naming Conventions |
| 37 | +- **PascalCase**: Classes, interfaces (with `I` prefix), methods, properties, events, enums, delegates, namespaces |
| 38 | +- **camelCase**: Private fields, local variables, parameters |
| 39 | +- **Static readonly fields**: PascalCase |
| 40 | +- **Constants**: PascalCase |
| 41 | +- **Generic type parameters**: PascalCase with `T` prefix |
| 42 | +- **No public/protected instance fields** - use properties instead |
| 43 | + |
| 44 | +#### Modifiers |
| 45 | +- Always specify accessibility modifiers explicitly |
| 46 | +- Order: `public`, `private`, `protected`, `internal`, `static`, `extern`, `new`, `virtual`, `abstract`, `sealed`, `override`, `readonly`, `unsafe`, `volatile`, `async` |
| 47 | + |
| 48 | +## Build and Test Requirements |
| 49 | + |
| 50 | +### Building the Project |
| 51 | +- **Always build in RELEASE mode** for validation: `dotnet build -c Release` |
| 52 | +- All warnings are treated as errors in Release configuration |
| 53 | +- Projects must be signed with strong name (`key.snk`) |
| 54 | +- Enable all analyzers: `AnalysisMode` is set to `AllEnabledByDefault` |
| 55 | + |
| 56 | +### Testing Requirements |
| 57 | +- **All tests must pass** before submitting changes |
| 58 | +- Run tests in Release mode: `dotnet test -c Release --no-restore` |
| 59 | +- Tests must be provided for every bug fix and feature |
| 60 | +- Test projects can use relaxed analyzer rules (see `tests/**/.editorconfig`) |
| 61 | +- Tests should be specific to the changes being made |
| 62 | +- Support for multiple test frameworks: xUnit, NUnit, MSTest, TUnit |
| 63 | + |
| 64 | +### Verification Steps |
| 65 | +Before submitting any changes, ensure: |
| 66 | +1. `dotnet restore` completes successfully |
| 67 | +2. `dotnet build -c Release` completes without warnings or errors |
| 68 | +3. `dotnet test -c Release` completes with all tests passing |
| 69 | +4. Code adheres to .editorconfig rules (enforced during build) |
| 70 | + |
| 71 | +## Code Quality and Analysis |
| 72 | + |
| 73 | +### Analyzers |
| 74 | +- **Microsoft Code Analysis**: Enabled with all rules |
| 75 | +- **StyleCop**: Enforced via .editorconfig |
| 76 | +- **Meziantou Analyzer**: Specific rules enabled |
| 77 | +- **SonarAnalyzer**: Enabled with specific suppressions |
| 78 | +- Code style violations are enforced in build (`EnforceCodeStyleInBuild: true`) |
| 79 | + |
| 80 | +### Code Analysis Rules |
| 81 | +- Default severity for .NET Code Style: **error** |
| 82 | +- `TreatWarningsAsErrors`: **true** in Release mode |
| 83 | +- Unused parameters must be removed (`IDE0060`) |
| 84 | +- Unnecessary suppressions must be removed (`IDE0079`) |
| 85 | + |
| 86 | +## Development Practices |
| 87 | + |
| 88 | +### Version Control |
| 89 | +- Follow **trunk-based development** - base changes on `main` branch |
| 90 | +- Use **Conventional Commits** style for commit messages |
| 91 | + - `feat:` for new features |
| 92 | + - `fix:` for bug fixes |
| 93 | + - `docs:` for documentation changes |
| 94 | + - `test:` for test additions/changes |
| 95 | + - `refactor:` for code refactoring |
| 96 | + - `chore:` for maintenance tasks |
| 97 | + |
| 98 | +### Pull Request Guidelines |
| 99 | +- Ensure repository can build successfully |
| 100 | +- All tests must pass |
| 101 | +- Follow existing coding conventions (aligned with ASP.NET Core team guidelines) |
| 102 | +- PRs should be focused and specific to the issue being addressed |
| 103 | +- Add/update tests to cover your changes |
| 104 | + |
| 105 | +## Project Structure |
| 106 | + |
| 107 | +### Main Projects |
| 108 | +- `bunit` - Main package with all functionality |
| 109 | +- `bunit.core` - Core testing functionality |
| 110 | +- `bunit.web` - Web-specific components testing |
| 111 | +- `bunit.web.query` - Testing-library.com query API implementation |
| 112 | +- `bunit.generators` - Source generators |
| 113 | +- `bunit.template` - Project templates (xUnit, NUnit, MSTest) |
| 114 | + |
| 115 | +### Test Projects |
| 116 | +- `bunit.tests` - Main test suite |
| 117 | +- `bunit.web.query.tests` - Query API tests |
| 118 | +- `bunit.generators.tests` - Source generator tests |
| 119 | +- `bunit.testassets` - Shared test assets |
| 120 | + |
| 121 | +## Additional Guidelines |
| 122 | + |
| 123 | +### Documentation |
| 124 | +- Update relevant documentation when making changes |
| 125 | +- Keep XML documentation comments current |
| 126 | +- Documentation must be clear and concise |
| 127 | +- Code examples should be tested and working |
| 128 | + |
| 129 | +### Dependencies |
| 130 | +- Central Package Management is enabled (`Directory.Packages.props`) |
| 131 | +- Follow semantic versioning for package references |
| 132 | +- Minimize external dependencies |
| 133 | + |
| 134 | +### Implicit Usings |
| 135 | +The following namespaces are automatically imported (except in template and generators projects): |
| 136 | +- `Microsoft.AspNetCore.Components` |
| 137 | +- `Microsoft.AspNetCore.Components.RenderTree` |
| 138 | +- `Microsoft.AspNetCore.Components.Rendering` |
| 139 | +- `Microsoft.Extensions.DependencyInjection` |
| 140 | +- `System.Runtime.Serialization` |
| 141 | +- `System.Diagnostics.CodeAnalysis` |
| 142 | + |
| 143 | +### Performance Considerations |
| 144 | +- Tests should run in milliseconds (not seconds) |
| 145 | +- Avoid blocking calls in async methods |
| 146 | +- Use `ConfigureAwait(false)` where appropriate (except in test code) |
| 147 | + |
| 148 | +### Code of Conduct |
| 149 | +- Follow the [.NET Foundation Code of Conduct](https://dotnetfoundation.org/code-of-conduct) |
| 150 | +- Be respectful and collaborative in all interactions |
| 151 | + |
| 152 | +## Quick Checklist for Copilot |
| 153 | + |
| 154 | +When making changes, always: |
| 155 | +- ✅ Use tabs for indentation |
| 156 | +- ✅ Enable nullable reference types |
| 157 | +- ✅ Use file-scoped namespaces |
| 158 | +- ✅ Build in Release mode (`-c Release`) |
| 159 | +- ✅ Run all tests in Release mode |
| 160 | +- ✅ Ensure no warnings (warnings = errors in Release) |
| 161 | +- ✅ Follow naming conventions (PascalCase for public, camelCase for private) |
| 162 | +- ✅ Add XML documentation for public APIs |
| 163 | +- ✅ Write tests for all changes |
| 164 | +- ✅ Use conventional commit message format |
| 165 | +- ✅ Verify all analyzer rules pass |
| 166 | +- ✅ Check that code compiles against all target frameworks (.NET 8, 9, 10) |
0 commit comments