Skip to content

contributing.md

Latest commit

 

History

History
76 lines (51 loc) · 2.15 KB

contributing.md

File metadata and controls

76 lines (51 loc) · 2.15 KB

Contributing Guide

Prerequisites

  • .NET 10 SDK
  • uv for the docs site (brew install uv or mise use uv)

Setup

dotnet tool restore   # csharpier + dotnet-api-docs
dotnet restore

Daily Commands

dotnet build --configuration Release
dotnet test  --configuration Release
dotnet csharpier format .

Docs

The site is built with mkdocs (Material) and served from GitHub Pages.

uv venv
uv pip install -r docs/requirements.txt
uv run mkdocs serve

If you change C# XML doc comments, regenerate the API reference first:

dotnet build JsonApiToolkit/JsonApiToolkit.csproj -c Release -o JsonApiToolkit/bin/docs
dotnet tool run dotnet-api-docs -- --input JsonApiToolkit/bin/docs --output docs/api --strict

Tests

Tests live in JsonApiToolkit.Tests/ and use xUnit + EF Core in-memory databases. Integration tests spin up a TestServer via HostBuilder; see existing tests in Integration/ for the pattern.

Naming: MethodName_Scenario_ExpectedBehavior (e.g. ApplyPagination_WithPageSizeZero_ClampsToOne).

When adding behavior, add tests covering the happy path, boundaries, and error conditions.

Commits

Conventional Commits, enforced indirectly by Release Please:

Prefix Bump Notes
fix: patch
feat: minor
feat!: / fix!: major breaking change
perf:, refactor:, docs:, build:, ci:, test:, style: none shows in changelog
chore: none hidden from changelog

Branch names: feat/, fix/, refactor/, docs/, test/, chore/, etc.

Pull Requests

  1. Branch from main.
  2. Format (dotnet csharpier format .) and run tests locally.
  3. Open a PR with a descriptive title and summary.
  4. CI must pass.
  5. At least one approving review is required.

Releases

Handled by Release Please. Merging to main updates a release PR that accumulates changes. Merging the release PR cuts a GitHub Release, publishes to NuGet, and bumps the version in JsonApiToolkit.csproj and mkdocs.yaml.

Questions

Open an issue: https://github.com/intility/json-api-toolkit/issues