Skip to content

Commit df793e2

Browse files
linkdotnetlinkdotnet
committed
feat: Instructions file
1 parent 32eaba0 commit df793e2

File tree

1 file changed

+166
-0
lines changed

1 file changed

+166
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
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

Comments
 (0)