Skip to content

Commit 24608eb

Browse files
TyKonKetTyKonKet
authored
Merge pull request #3 from TyKonKet/copilot/fix-7ca2238d-bf54-4ab3-ac32-1dcff0360c78
Add comprehensive .github/copilot-instructions.md to onboard coding agents
2 parents f2db291 + aff0e7f commit 24608eb

File tree

1 file changed

+216
-0
lines changed

1 file changed

+216
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# Copilot Instructions for BarcodeGenerator Repository
2+
3+
## Repository Overview
4+
5+
**BarcodeGenerator** is a .NET library for generating barcodes using SkiaSharp. The library supports multiple barcode types (EAN-13, UPC-A, ISBN-13, EAN-8, CODE-93) and provides a fluent API for configuration and export. It's distributed as a NuGet package and targets multiple .NET frameworks.
6+
7+
**Repository Size**: Medium (~50 source files)
8+
**Project Type**: .NET Class Library
9+
**Languages**: C# (.NET Standard 2.0, .NET 6.0, .NET 8.0, .NET Framework 4.6.2)
10+
**Main Dependencies**: SkiaSharp 3.116.1, System.ValueTuple
11+
**Test Framework**: xUnit with BenchmarkDotNet for performance testing
12+
13+
## Build Instructions
14+
15+
### Prerequisites
16+
- **.NET SDK 9.x** is required for full solution build (test projects target .NET 9.0)
17+
- If only .NET 8.x is available, you can build the main library individually
18+
- Linux: SkiaSharp.NativeAssets.Linux.NoDependencies provides native dependencies
19+
20+
### Working Build Commands
21+
22+
**Build main library only** (works with .NET 8.x):
23+
```bash
24+
cd TyKonKet.BarcodeGenerator
25+
dotnet restore
26+
dotnet build --configuration Release
27+
```
28+
29+
**Full solution build** (requires .NET 9.x):
30+
```bash
31+
dotnet restore
32+
dotnet build --configuration Release
33+
```
34+
35+
**Run tests** (requires .NET 9.x):
36+
```bash
37+
cd Tests/TyKonKet.BarcodeGenerator.Tests
38+
dotnet test --configuration Release --logger "GitHubActions;summary.includePassedTests=true;summary.includeSkippedTests=true"
39+
```
40+
41+
**Run benchmarks** (requires .NET 9.x):
42+
```bash
43+
cd Tests/TyKonKet.BarcodeGenerator.CB
44+
dotnet run --configuration Release --exporters json --filter '*'
45+
```
46+
47+
### Known Build Issues
48+
- **CRITICAL**: Test projects target .NET 9.0 and will fail with earlier SDK versions
49+
- Solution-level `dotnet restore` fails with .NET 8.x due to targeting conflicts
50+
- **Workaround**: Build main library individually or upgrade to .NET 9.x SDK
51+
- Build warnings are expected from static analyzers (not errors)
52+
53+
### Build Time Expectations
54+
- Main library build: ~20 seconds
55+
- Full solution build: ~45 seconds
56+
- Test execution: ~30 seconds
57+
- Benchmark run: ~2-5 minutes
58+
59+
## Validation Pipeline
60+
61+
### Continuous Integration
62+
The repository uses GitHub Actions with two main workflows:
63+
64+
**Test Runner** (`.github/workflows/dotnet_test_runner.yml`):
65+
- Triggers: Push to master, manual dispatch
66+
- Environment: Ubuntu latest with .NET 9.x
67+
- Command: `dotnet test --configuration Release` in test directory
68+
- Always run tests before committing changes
69+
70+
**Benchmark Runner** (`.github/workflows/dotnet_benchmark_runner.yml`):
71+
- Triggers: Push to master, manual dispatch
72+
- Runs performance regression checks
73+
- Publishes results to GitHub Pages
74+
- Alerts on >200% performance degradation
75+
76+
### Code Quality Checks
77+
The project enforces strict code quality with multiple analyzers:
78+
79+
**Always run before committing**:
80+
```bash
81+
dotnet build --configuration Release
82+
```
83+
84+
**Enabled Analyzers**:
85+
- Microsoft.CodeAnalysis.NetAnalyzers (built-in .NET analyzers)
86+
- SonarAnalyzer.CSharp (code quality)
87+
- StyleCop.Analyzers (style consistency)
88+
- Meziantou.Analyzer (additional rules)
89+
- Roslynator.Analyzers (refactoring suggestions)
90+
- Multiple specialized analyzers (IDisposableAnalyzers, ErrorProne.NET, etc.)
91+
92+
**Configuration**: `.editorconfig` disables some StyleCop rules, `EnforceCodeStyleInBuild=True` is enabled
93+
94+
## Project Layout and Architecture
95+
96+
### Solution Structure
97+
```
98+
TyKonKet.BarcodeGenerator.sln # Main solution file
99+
├── TyKonKet.BarcodeGenerator/ # Main library project
100+
│ ├── Barcode.cs # Main API entry point
101+
│ ├── BarcodeOptions.cs # Configuration options
102+
│ ├── BarcodeTypes.cs # Supported barcode types enum
103+
│ ├── Encoders/ # Encoder implementations
104+
│ │ ├── Abstract/ # Base classes and interfaces
105+
│ │ ├── Ean13Encoder.cs # EAN-13 implementation
106+
│ │ ├── UpcaEncoder.cs # UPC-A implementation
107+
│ │ ├── Ean8Encoder.cs # EAN-8 implementation
108+
│ │ ├── Isbn13Encoder.cs # ISBN-13 implementation
109+
│ │ └── Code93Encoder.cs # CODE-93 implementation
110+
│ ├── Fonts/ # Font handling utilities
111+
│ ├── Utils/ # Helper utilities
112+
│ └── TyKonKet.BarcodeGenerator.csproj # Project file
113+
├── Tests/ # Test projects folder
114+
│ ├── TyKonKet.BarcodeGenerator.Tests/ # Unit tests (xUnit)
115+
│ ├── TyKonKet.BarcodeGenerator.Benchmarks/ # Performance tests
116+
│ ├── TyKonKet.BarcodeGenerator.Playground/ # Development testing
117+
│ └── TyKonKet.BarcodeGenerator.CB/ # CI benchmarks
118+
└── Directory.Build.props # MSBuild properties
119+
```
120+
121+
### Key Configuration Files
122+
- `Directory.Build.props`: Defines artifacts path for build output
123+
- `.editorconfig`: Code style configuration, disables some StyleCop rules
124+
- `.gitignore`: Standard Visual Studio ignore patterns + artifacts/ folder
125+
- `TyKonKet.BarcodeGenerator.csproj`: Multi-targeting, NuGet package configuration
126+
127+
### Architectural Patterns
128+
**Factory Pattern**: `EncodersFactory.Create()` instantiates encoders based on barcode type
129+
**Options Pattern**: `BarcodeOptions` class with fluent configuration API
130+
**Template Method**: Abstract `Encoder` base class with virtual methods
131+
**Dependency Injection**: Options injected into encoders via constructor
132+
133+
### Core API Usage
134+
```csharp
135+
using var barcode = new Barcode(options =>
136+
{
137+
options.Type = BarcodeTypes.Code93;
138+
options.Height = 30;
139+
options.Scaling = 10;
140+
options.RenderText = true;
141+
});
142+
string validatedBarcode = barcode.Encode("THE-BARCODE");
143+
barcode.Export("path/{barcode}.png", SKEncodedImageFormat.Png, 100);
144+
```
145+
146+
## Important Dependencies and Constraints
147+
148+
### Framework Targeting
149+
- **.NET Standard 2.0**: Core compatibility target
150+
- **.NET Framework 4.6.2**: Legacy Windows support
151+
- **.NET 6.0**: LTS version support
152+
- **.NET 8.0**: Current stable version
153+
154+
### Runtime Dependencies
155+
- **SkiaSharp 3.116.1**: Cross-platform 2D graphics (core dependency)
156+
- **SkiaSharp.NativeAssets.Linux.NoDependencies**: Linux native support
157+
- **System.ValueTuple 4.5.0**: Compatibility for older frameworks
158+
159+
### Breaking Changes (v2.0.0+)
160+
- No longer supports .NET Standard 1.3 (requires 2.0+)
161+
- API redesigned for better usability and customization
162+
- SkiaSharp updated to 3.116.1
163+
164+
## Testing Guidelines
165+
166+
### Unit Tests Structure
167+
Tests are organized by encoder type using xUnit framework:
168+
```
169+
Tests/TyKonKet.BarcodeGenerator.Tests/Encoders/
170+
├── Abstract/EncoderTest.cs # Base encoder tests
171+
├── Ean13EncoderTest.cs # EAN-13 specific tests
172+
├── UpcaEncoderTest.cs # UPC-A specific tests
173+
└── [other encoder tests]
174+
```
175+
176+
**Test Patterns**:
177+
- Use `[Theory]` with `[InlineData]` for parametrized tests
178+
- Test both valid and invalid input scenarios
179+
- Validate barcode formatting and check digit calculations
180+
- Use `Assert.Throws<ExceptionType>()` for error conditions
181+
182+
### Performance Testing
183+
BenchmarkDotNet tests in `TyKonKet.BarcodeGenerator.CB` measure:
184+
- Encoding performance per barcode type
185+
- Memory allocation patterns
186+
- Regression detection (200% threshold)
187+
188+
## Key File Locations
189+
190+
**Build Configuration**:
191+
- Solution file: `TyKonKet.BarcodeGenerator.sln`
192+
- Main project: `TyKonKet.BarcodeGenerator/TyKonKet.BarcodeGenerator.csproj`
193+
- Build properties: `Directory.Build.props`
194+
195+
**Core Source Files**:
196+
- Entry point: `TyKonKet.BarcodeGenerator/Barcode.cs`
197+
- Options: `TyKonKet.BarcodeGenerator/BarcodeOptions.cs`
198+
- Encoders: `TyKonKet.BarcodeGenerator/Encoders/`
199+
200+
**Testing**:
201+
- Unit tests: `Tests/TyKonKet.BarcodeGenerator.Tests/`
202+
- Test config: `Tests/TyKonKet.BarcodeGenerator.Tests/TyKonKet.BarcodeGenerator.Tests.csproj`
203+
204+
**CI/CD**:
205+
- Test workflow: `.github/workflows/dotnet_test_runner.yml`
206+
- Benchmark workflow: `.github/workflows/dotnet_benchmark_runner.yml`
207+
208+
## Recommended Workflow for Code Changes
209+
210+
1. **Before making changes**: Run `dotnet build --configuration Release` in `TyKonKet.BarcodeGenerator/` to ensure clean build
211+
2. **Making changes**: Focus on single encoder or core functionality to minimize impact
212+
3. **Testing changes**: If .NET 9.x available, run full test suite; otherwise validate with manual testing
213+
4. **Before committing**: Ensure build completes without NEW warnings/errors (existing analyzer warnings are acceptable)
214+
5. **Trust these instructions**: Only search for additional information if the instructions are incomplete or incorrect
215+
216+
The repository is well-structured and builds reliably when using the correct .NET SDK version. Focus on the main library for most changes, as the test projects have additional version requirements.

0 commit comments

Comments
 (0)