Skip to content

Commit 92c97b5

Browse files
Copilotglennawatson
Copilot
and
glennawatson
authored
✨ Set up Copilot instructions for Splat.DI.SourceGenerator (#275)
* Initial plan * Add Copilot instructions for Splat DI Source Generator Co-authored-by: glennawatson <5834289+glennawatson@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: glennawatson <5834289+glennawatson@users.noreply.github.com>
1 parent 450edb7 commit 92c97b5

File tree

1 file changed

+154
-0
lines changed

1 file changed

+154
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Splat DI Source Generator: Dependency Injection Code Generation
2+
3+
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.
4+
5+
## Working Effectively
6+
7+
### Prerequisites and Environment Setup
8+
- **CRITICAL**: Requires .NET 9.0 SDK (not .NET 8.0). Install with:
9+
```bash
10+
curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --version latest --channel 9.0
11+
export PATH="$HOME/.dotnet:$PATH"
12+
```
13+
- **Platform Support**: This project **builds fully only on Windows**. Linux/macOS have partial support due to ILRepack tooling requirements.
14+
- **Development Tools**: Visual Studio 2022 or VS Code with C# extension.
15+
16+
### Code Style and Analysis Enforcement
17+
- **EditorConfig Compliance**: Repository uses comprehensive `.editorconfig` with 500+ rules for C# formatting, naming conventions, and code analysis
18+
- **StyleCop Analyzers**: Enforces consistent C# code style with `stylecop.analyzers` (v1.2.0-beta.556)
19+
- **Roslynator Analyzers**: Additional code quality rules with `Roslynator.Analyzers` (v4.14.0)
20+
- **Analysis Level**: Set to `latest` with enhanced .NET analyzers enabled
21+
- **CRITICAL**: All code must comply with **ReactiveUI contribution guidelines**: https://www.reactiveui.net/contribute/index.html
22+
23+
### Code Formatting (Fast - Always Run)
24+
- **ALWAYS** run formatting before committing:
25+
```bash
26+
cd src
27+
dotnet format whitespace --verify-no-changes
28+
dotnet format style --verify-no-changes
29+
```
30+
Time: **2-5 seconds per command**.
31+
32+
## Project Overview
33+
34+
### What is Splat DI Source Generator?
35+
This project is a source generator that produces Splat-based registrations for both constructor and property injection. It eliminates the need for reflection by using C# Source Generation to create dependency injection registrations at compile time.
36+
37+
### Key Features
38+
- **Constructor Injection**: Automatic registration generation based on constructor parameters
39+
- **Property Injection**: Support for `[DependencyInjectionProperty]` attribute on properties
40+
- **Lazy Singleton Support**: `RegisterLazySingleton<TInterface, TImplementation>()` for singleton instances
41+
- **No Reflection**: Full native speed through compile-time code generation
42+
- **Splat Integration**: Seamless integration with the Splat service location framework
43+
44+
## Common Development Tasks
45+
46+
### Source Generator Development
47+
1. **Follow Roslyn Source Generator best practices** - see Microsoft documentation on source generators
48+
2. **Ensure StyleCop compliance** - all code must pass StyleCop analyzers (SA* rules)
49+
3. **Run code analysis** - `dotnet build` must complete without analyzer warnings
50+
4. **Add unit tests** - use Microsoft.CodeAnalysis.Testing for source generator tests
51+
5. **Update documentation** - especially for public APIs with XML doc comments
52+
6. **Test generated code** - verify the output compiles and behaves correctly
53+
54+
### Adding New Features
55+
1. **Follow coding standards** - see ReactiveUI guidelines: https://www.reactiveui.net/contribute/index.html
56+
2. **Ensure cross-platform compatibility** - while builds require Windows, generated code should work everywhere
57+
3. **Add comprehensive tests** - test both the generator and the generated code
58+
4. **Update README.md** - document new attributes or registration methods
59+
5. **Consider performance** - source generators run during compilation
60+
61+
### Testing Source Generators
62+
- Use `Microsoft.CodeAnalysis.Testing` framework for testing source generators
63+
- Test both successful generation and error cases
64+
- Verify generated code compiles and produces expected registrations
65+
- Test edge cases like multiple constructors, missing dependencies, etc.
66+
67+
## CI/CD Integration
68+
69+
### GitHub Actions (Windows-based)
70+
- Uses `reactiveui/actions-common` workflow
71+
- Requires Windows runner for full build due to ILRepack tooling
72+
- Installs all workloads automatically
73+
- Runs comprehensive test suite and uploads coverage
74+
75+
### Local Development
76+
- **Use** Linux/macOS for quick iteration on core source generator logic
77+
- **Format code** before every commit
78+
- **Test generated output** when changing generation logic
79+
- **Full builds require Windows** due to IL merging requirements
80+
81+
## Troubleshooting
82+
83+
### Common Issues
84+
1. **"ILRepack not found" errors**: Platform limitation - use Windows for full builds
85+
2. **"Invalid framework identifier" errors**: Use explicit `-p:TargetFramework=netstandard2.0`
86+
3. **Source generator not running**: Clean and rebuild, ensure generator is referenced correctly
87+
4. **Build hangs**: Normal for large builds - wait up to 45 minutes
88+
5. **Test failures**: May be platform-specific - verify on Windows
89+
90+
### Quick Fixes
91+
- **Format issues**: Run `dotnet format whitespace` and `dotnet format style`
92+
- **StyleCop violations**: Check `.editorconfig` rules and `src/stylecop.json` configuration
93+
- **Analyzer warnings**: Build with `--verbosity normal` to see detailed analyzer messages
94+
- **Missing XML documentation**: All public APIs require XML doc comments per StyleCop rules
95+
- **Package restore issues**: Clear NuGet cache with `dotnet nuget locals all --clear`
96+
- **Generator not working**: Verify `<Analyzer Include="..." />` references in consuming projects
97+
98+
### When to Escalate
99+
- **Source generator compilation errors** affecting code generation
100+
- **Cross-platform compatibility** issues affecting generated code
101+
- **Performance regressions** in generator execution time
102+
- **Test failures** that persist across platforms
103+
- **Build system changes** affecting CI/CD pipeline
104+
105+
## Development Patterns
106+
107+
### Source Generator Structure
108+
- **Incremental Generators**: Use `IIncrementalGenerator` for better performance
109+
- **Syntax Receivers**: Implement efficient syntax filtering for DI attributes
110+
- **Code Generation**: Generate clean, readable C# code with proper formatting
111+
- **Error Handling**: Provide clear diagnostics for invalid usage patterns
112+
113+
### Dependency Injection Patterns
114+
- **Constructor Injection**: Primary pattern for mandatory dependencies
115+
- **Property Injection**: For optional dependencies with `[DependencyInjectionProperty]`
116+
- **Lazy Dependencies**: Use `Lazy<T>` for expensive-to-create dependencies
117+
- **Service Location**: Integration with Splat's `Locator.Current`
118+
119+
## Resources
120+
121+
### Governance & Contributing
122+
- **Contribution Hub**: https://www.reactiveui.net/contribute/index.html
123+
- **ReactiveUI Repository README**: https://github.com/reactiveui/ReactiveUI#readme
124+
- **Contributing Guidelines**: https://github.com/reactiveui/ReactiveUI/blob/main/CONTRIBUTING.md
125+
- **Code of Conduct**: https://github.com/reactiveui/ReactiveUI/blob/main/CODE_OF_CONDUCT.md
126+
127+
### Engineering & Style
128+
- **ReactiveUI Coding/Style Guidance** (start here): https://www.reactiveui.net/contribute/
129+
- **Build & Project Structure Reference**: https://github.com/reactiveui/ReactiveUI#readme
130+
131+
### Source Generator Resources
132+
- **Source Generators Documentation**: https://learn.microsoft.com/dotnet/csharp/roslyn-sdk/source-generators-overview
133+
- **Microsoft.CodeAnalysis.Testing**: https://github.com/dotnet/roslyn-sdk/tree/main/src/Microsoft.CodeAnalysis.Testing
134+
- **Incremental Generators**: https://github.com/dotnet/roslyn/blob/main/docs/features/incremental-generators.md
135+
- **Source Generator Cookbook**: https://github.com/dotnet/roslyn/blob/main/docs/features/source-generators.cookbook.md
136+
137+
### Ecosystem
138+
- **Splat** (service location/DI and logging): https://github.com/reactiveui/splat
139+
- **DynamicData** (reactive collections): https://github.com/reactivemarbles/DynamicData
140+
- **ReactiveUI.SourceGenerators**: https://github.com/reactiveui/ReactiveUI.SourceGenerators
141+
142+
### Source Generators & AOT/Trimming
143+
- **ReactiveUI.SourceGenerators**: https://github.com/reactiveui/ReactiveUI.SourceGenerators
144+
- **.NET Native AOT Overview**: https://learn.microsoft.com/dotnet/core/deploying/native-aot/
145+
- **Prepare Libraries for Trimming**: https://learn.microsoft.com/dotnet/core/deploying/trimming/prepare-libraries-for-trimming
146+
- **Trimming Options (MSBuild)**: https://learn.microsoft.com/dotnet/core/deploying/trimming/trimming-options
147+
- **Fixing Trim Warnings**: https://learn.microsoft.com/dotnet/core/deploying/trimming/trim-warnings
148+
149+
### Copilot Coding Agent
150+
- **Best Practices for Copilot Coding Agent**: https://gh.io/copilot-coding-agent-tips
151+
152+
### CI & Misc
153+
- **GitHub Actions** (Windows builds and workflow runs): https://github.com/reactiveui/Splat.DI.SourceGenerator/actions
154+
- **ReactiveUI Website Source** (useful for docs cross-refs): https://github.com/reactiveui/website

0 commit comments

Comments
 (0)