how to contribute patterns and conventions

Patterns and conventions

Coding style

• C# 14 (net10.0), file-scoped namespaces, nullable reference types, switch expressions, pattern matching
• Warnings as Errors enabled via Directory.Build.props (TreatWarningsAsErrors=true)
• EnableNETAnalyzers=true, AnalysisLevel=latest, AnalysisMode=latest-Recommended
• AnalysisModeSecurity=All for security-focused rules
• Deterministic=true for reproducible builds
• InvariantGlobalization=true for culture-invariant string operations

Analyzers

The project uses multiple Roslyn analyzer packages configured in Directory.Build.props:

Analyzer	Purpose
Roslynator.Analyzers	Code quality and refactoring rules
Roslynator.Formatting.Analyzers	Formatting enforcement
Roslynator.CodeAnalysis.Analyzers	Roslyn API usage rules
Meziantou.Analyzer	Additional best-practice rules
Microsoft.CodeAnalysis.BannedApiAnalyzers	Banned API enforcement via BannedSymbols.txt
FgrFlatAccessAnalyzer (custom)	Enforces architectural boundaries on FileGenerationRequest

Performance rules

• Distribution algorithms must be O(1) per file
• Use Span<T>, ArrayPool<T> in hot paths, avoid allocations
• ZIP entry paths always use /; normalize to backslashes with .Replace('/', '\\')
• Never use Replace(Path.DirectorySeparatorChar, '\\') (no-op on Windows)

Domain language

All code, comments, documentation, and reviews must use canonical terms from UBIQUITOUS_LANGUAGE.md. Non-canonical terms are flagged in review even when they seem simpler.

Test naming

• Class: {Subject}Tests (e.g., BatesNumberGeneratorTests)
• Method: {Method}_{Scenario}_{Expected} (e.g., Generate_WithCustomPrefix_ShouldIncludePrefix)

Output parity

Before refactoring code producing Load File / Audit File / Production Set output, capture a seeded golden baseline as a content-hash manifest. Diff after every step. Byte-for-byte parity is what makes it safe to restructure writers. Preserve historical output quirks (EOL, encoding, path separators) exactly.

No copyright headers

Do not add // <copyright ...> or file-level license headers. This is an intentional project convention enforced by the .coderabbit.yaml review instructions.

Error handling

• Fix root causes, not symptoms. Never implement workarounds.
• If you cannot find the root cause, compile what you have learned and report it.
• Tests must verify real outcomes, not mocked behavior.