Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
148 lines (117 loc) · 6.99 KB

CONTRIBUTING.md

File metadata and controls

148 lines (117 loc) · 6.99 KB
Raw

Contributing to CaeriusNet

Thanks for considering a contribution! CaeriusNet is a tightly-scoped, opinionated micro-ORM for C# 14 / .NET 10 / SQL Server, focused on stored procedures, TVPs, and transactions. This document explains how to set up, the conventions we follow, and how to get a PR merged efficiently.

Changes targeting the major release must also preserve the invariants and evidence listed in the 11.2.0 engineering contract.

Table of Contents

Code of Conduct

This project follows the Contributor Covenant 2.1. By participating you agree to uphold it.

Quick start

Local

git clone https://github.com/CaeriusNET/CaeriusNet.git
cd CaeriusNet
dotnet restore CaeriusNet.slnx --locked-mode
dotnet build   CaeriusNet.slnx -c Release --no-restore -p:TreatWarningsAsErrors=true
dotnet test    CaeriusNet.slnx -c Release --no-build --filter "FullyQualifiedName!~CaeriusNet.IntegrationTests"

Devcontainer (recommended)

Open the repository in VS Code or JetBrains Rider with the Dev Containers extension. The container ships .NET 10, Docker-outside-of-Docker (so Testcontainers works), the GitHub CLI and pre-pulls the SQL Server 2022 image.

# Inside the container — run the full integration suite
CAERIUS_RUN_CONTAINERS=true \
  dotnet test tests/CaeriusNet.IntegrationTests/CaeriusNet.IntegrationTests.csproj -c Release

Project layout

src/CaeriusNet/                         # Core runtime package
src/CaeriusNet.Redis/                   # Redis integration package
src/CaeriusNet.Aspire/                  # Aspire integration package
src/CaeriusNet.Contracts/               # AutoContracts package assets
src/Compiler/                           # Generator, analyzer, build-only generator and shared sources
tests/CaeriusNet.Tests/                 # Pure runtime unit tests
tests/CaeriusNet.Generator.Tests/       # Source-generator and incrementality tests
tests/CaeriusNet.Analyzer.Tests/        # Analyzer diagnostic tests
tests/CaeriusNet.IntegrationTests/      # SQL Server, Redis, Aspire and Contracts acceptance tests
tests/CaeriusNet.Packaging.Tests/       # Exact NuGet package validation
benchmarks/                             # BenchmarkDotNet suites and performance gate
examples/                               # Example consumer applications
tools/                                  # SQL Server contract discovery tool
docs/                                   # VitePress site and engineering contracts
.devcontainer/                          # Reproducible development environment
.github/                                # Workflows, templates and validation scripts

Branching & commits

  • Base branch: main.
  • Feature branches: feature/<short-kebab>.
  • Fix branches: fix/<short-kebab>.
  • Chore/docs branches: chore/<short-kebab> / docs/<short-kebab>.

We use Conventional Commits. Common types:

Type When
feat A new public API or behaviour
fix A bug fix
perf A performance improvement (back it with a bench)
refactor Internal change with no external behaviour delta
test Adding or improving tests
docs Documentation only
chore Tooling, CI, dependency updates

If your change is breaking, append ! (e.g. feat(sproc)!:) and mention the migration path in the PR description.

Build, test & coverage

Command Purpose
dotnet build CaeriusNet.slnx -c Release -p:TreatWarningsAsErrors=true Mirrors CI.
dotnet test CaeriusNet.slnx -c Release --filter "FullyQualifiedName!~IntegrationTests" Unit + generator tests (fast, no Docker).
dotnet test tests/CaeriusNet.IntegrationTests End-to-end tests; needs Docker.
pwsh ./.github/scripts/ValidatePackage.ps1 -Configuration Release -OutputDirectory .work/package-validation Packs the NuGet package and smoke-tests a consumer project.
cd docs && npm install && npm run docs:build Builds the VitePress docs when npm is available; use npm ci if a lockfile exists.
dotnet test --collect:"XPlat Code Coverage" Generates Cobertura coverage.

Coverage is reported on every PR via the CI workflow. Aim to never decrease line coverage on src/CaeriusNet/ and src/Compiler/CaeriusNet.Generator/.

Coding conventions

  • Target framework: net10.0 (no multi-target).
  • Language version: latest (C# 14).
  • Nullable: enabled everywhere.
  • Async only. No sync over async; use ConfigureAwait(false) in library code.
  • Stored procedures only. Do not introduce inline SQL or query builders.
  • No reflection on the hot path. Reach for source generators or Span<T>/Memory<T> first.
  • sealed by default for both DTOs and helper classes.
  • Single-responsibility files. One public type per file when practical.
  • XML doc comments on every public API (we ship as a NuGet package).
  • No new dependencies without prior discussion in an issue.

Static analysis is enforced via TreatWarningsAsErrors=true. Prefer fixing the root cause over a #pragma warning disable.

Pull request process

  1. Open an issue first for non-trivial changes so we can align on direction.
  2. Use a focused branch with the prefix described above.
  3. Keep PRs small and reviewable. Split refactors from features.
  4. CI must be green (build, non-integration tests, package validation, CodeQL, dependency review, and docs build when docs changed).
  5. Run Docker-backed integration tests when storage, transactions, SQL, or TVP behaviour changes.
  6. Update CHANGELOG.md under the [Unreleased] section.
  7. Update README / docs when public behaviour changes.
  8. Release PRs must leave clear release notes in the PR or changelog so the manual release workflow can publish a tagged NuGet package with generated or supplied notes.
  9. At least one approving review is required before merge.
  10. PRs are squash-merged onto main with a Conventional Commit title.

Reporting bugs / requesting features

Use the issue templates — they ask for the minimum context (target framework, SqlClient version, repro snippet) we need to triage quickly.

Security

Please do not report vulnerabilities via public issues. Follow the process in SECURITY.md.