ersatztv/docs/contributing.md

Contributing to the ErsatzTV fork

A descriptive guide to the conventions already in this codebase — written so future changes (human or AI) extend the established architecture instead of reinventing it. It's a living document: update it when a pattern legitimately evolves.

The guiding principle

Match the established style and patterns. Diverge only when there's a genuinely strong reason — when it's the real best or only option — even if that means rearchitecting. Never deviate gratuitously or just because a different approach is locally convenient. When a deviation is justified, state why (in the PR/commit, and in code comments where it'll surprise a reader).

Several of the rules below are now enforced in CI (layering tests, analyzers, formatting, migration checks) — see the pointers per section.

1. Architecture & layering

CQRS via MediatR. Dependency direction is enforced by ErsatzTV.Architecture.Tests (NetArchTest):

Project	Responsibility	May depend on
ErsatzTV.FFmpeg	ffmpeg process/pipeline wrapper	(nothing — lowest layer)
ErsatzTV.Core	domain entities, interfaces, pure logic	FFmpeg only — no EF Core, no Infrastructure/Application
ErsatzTV.Infrastructure	EF Core data access, external clients	Core
ErsatzTV.Infrastructure.Sqlite / .MySql	provider-specific EF (migrations)	Core, Infrastructure
ErsatzTV.Application	MediatR handlers (business logic)	Core, Infrastructure (the abstraction, not the concrete providers)
ErsatzTV.Scanner	library scanning host	Core, Infrastructure*
ErsatzTV	ASP.NET Core host, Blazor, controllers, DI composition root	everything

If a test fails here, the fix is almost always to move the type, not to relax the rule. (ersatztv#12)

2. CQRS handler conventions

• Requests are record types named for the action — GetX / CreateX / UpdateX / DeleteX — implementing IRequest<TResult>, living under <Domain>/Queries/ or <Domain>/Commands/ next to their handler.
• Result types (LanguageExt, see §3): queries return Option<T> or List<T>; commands return Option<BaseError> (void success) or Either<BaseError, T> (value success).
• Handlers implement IRequestHandler<TRequest, TResult> with primary-constructor DI and an async Task<TResult> Handle(TRequest request, CancellationToken cancellationToken).
• Validation lives in the handler as private static methods returning Validation<BaseError, T>, composed with tuple .Apply(...) — not FluentValidation or MediatR pipeline behaviors.
• Examples: ErsatzTV.Application/Channels/Queries/GetChannelById.cs (+ …/GetChannelByIdHandler.cs, Option<ChannelViewModel>), ErsatzTV.Application/FFmpegProfiles/Commands/DeleteFFmpegProfileHandler.cs (tuple-Apply validation → Either<BaseError, Unit>).

3. Functional style (LanguageExt)

Every project globally imports using static LanguageExt.Prelude;. Use the monads instead of exceptions for control flow.

• Option<T> — Optional(x), Some/None, HeadOrNone() to pluck from a collection; branch with Match/MatchAsync(onSome, onNone); default with IfNone(...); transform with Map/Bind; foreach (var x in option) to unpack conditionally.
• Either<BaseError, T> / Validation<BaseError, T> — the error backbone. BaseError.New("…") for failures, Unit.Default for void success. Accumulate multiple checks with Validation (tuple .Apply((a, b, c) => …)) then ToEither(). MapLeft to transform errors.
• Examples: ErsatzTV.Core/FFmpeg/…, ErsatzTV.Application/FFmpegProfiles/Commands/DeleteFFmpegProfileHandler.cs.

4. Blazor / MudBlazor UI

• Keep pages thin — inject IMediator and await Mediator.Send(new SomeQuery(...), token); no business logic or data access in the component.
• Pages @implements IDisposable and own a CancellationTokenSource per lifecycle phase, cancelled on parameter change / disposal.
• Forms: MudForm + Blazored FluentValidation (Validation="@(validator.ValidateValue)", For="@(() => _model.Prop)"); surface errors via Snackbar.Add(msg, Severity.Error).
• Dialogs: pass DialogParameters, accept [CascadingParameter] IMudDialogInstance, close with MudDialog.Close(DialogResult.Ok(...)). Global providers + event subscriptions live in Shared/MainLayout.razor (unsubscribed in Dispose()).
• Examples: ErsatzTV/Pages/Channels.razor, ErsatzTV/Pages/ChannelEditor.razor, ErsatzTV/Shared/ChannelPreviewDialog.razor.

5. Data access & EF Core

• TvContext (ErsatzTV.Infrastructure/Data/TvContext.cs) is the single DbContext; resolve it via IDbContextFactory<TvContext> in handlers.
• Two providers: ErsatzTV.Infrastructure.Sqlite (the prod default, /config/ersatztv.sqlite3) and …MySql, each with its own Migrations/ set + TvContextModelSnapshot. The provider is chosen by the provider config key in Startup.
• A model change needs a migration in BOTH providers — run scripts/add-migration.sh <Name>. CI's migrations job enforces model-drift + apply-to-fresh-DB per provider (see docs/ci-cd.md → Migration integrity). Review non-transactional ops (e.g. SQLite PRAGMA foreign_keys) carefully. (ersatztv#13)

6. FFmpeg pipeline

• Step-based composition: each task is an IPipelineStep (ErsatzTV.FFmpeg/IPipelineStep.cs) that contributes GlobalOptions/InputOptions/FilterOptions/OutputOptions and a NextState() that threads frame metadata (pixel format, data location, dimensions). CommandGenerator.GenerateArguments assembles the steps into the final argument list.
• Detect capabilities at runtime; don't hardcode — IHardwareCapabilities implementations (Vaapi/Nvidia/… HardwareCapabilities) report available codecs/profiles, and builders pick the encoder/decoder accordingly.
• Version-gate features explicitly — e.g. Capabilities/NvidiaHardwareCapabilities.cs parses FFmpegCapabilities.Version and disables 10-bit H.264 decode hwaccel below ffmpeg 8. Follow this pattern for the ffmpeg 8 upgrade (ersatztv#9).
• Examples: ErsatzTV.FFmpeg/Encoder/EncoderBase.cs, ErsatzTV.FFmpeg/Filter/ScaleFilter.cs.

7. Naming, formatting, analyzers

• .editorconfig is the source of truth for formatting + rule severities (plus ErsatzTV.sln.DotSettings for ReSharper). Run dotnet format before committing.
• TreatWarningsAsErrors=true in the app projects — a warning fails the build. NoWarn carries a small, documented exemption list (e.g. VSTHRD200, CA1873); NuGet-audit NU1901-1903 are demoted to warnings in Directory.Build.props while NU1904 (critical) blocks.
• Static-analysis packs (Roslynator, SonarAnalyzer, Meziantou, AsyncFixer) run at suggestion and are promoted to warning/error rule-by-rule; promotion is the enforcement (the TWAE build). New rules start at suggestion — never flip a wall of rules to error at once. (ersatztv#15)

8. Testing

• NUnit ([TestFixture]/[Test]/[TestCase]) + Shouldly (.ShouldBe(...)) + NSubstitute
  • Testably.Abstractions for a fake filesystem. xUnit is not used. Tests live in *.Tests projects mirroring the source.
• Established kinds: FFmpeg command-string assertions (build a pipeline → assert the exact arg string — ErsatzTV.FFmpeg.Tests/PipelineBuilderBaseTests.cs); golden-file tests for Jellyfin-facing output (ErsatzTV.Core.Tests/Iptv/ChannelPlaylistGoldenTests.cs, regen via ETV_UPDATE_GOLDENS=1, ersatztv#11); architecture tests (§1, ersatztv#12).
• The suite is timezone-independent — the previously timezone-sensitive DateTimeOffset filler-scheduling tests were fixed (ersatztv#24) by giving fixtures realistic times instead of the default DateTime.MinValue, which underflowed DateTimeOffset.MinValue under a non-UTC offset. When constructing test PlayoutItems, set a real Start (e.g. startState.CurrentTime.UtcDateTime), not the default. CI runs UTC and uses dotnet test … --blame-hang-timeout 2m.

9. Build / CI

• Central Package Management: versions live in the repo-root Directory.Packages.props; csproj reference packages by name only — never put Version= back on a <PackageReference> (NU1008). Repo-wide MSBuild config is in Directory.Build.props / Directory.Build.targets. (ersatztv#14)
• The Gitea Actions pipeline (.gitea/workflows/docker-build.yml): test → migrations → build (image + smoke/IPTV-E2E). Renovate opens dependency PRs; a weekly dependency-scan surfaces advisories. Full details: docs/ci-cd.md.
• Versioning is CalVer vYY.<release-seq>.<patch> (not year.month); never [skip ci] a commit you'll tag. See docs/ci-cd.md → Versioning.

10. Deviation policy

Re-stating §0 because it's the whole point: follow the established pattern; diverge only with a concrete, stated reason. Record an intentional departure in the PR description and a code comment at the point of surprise (e.g. "using X instead of the usual Y because …"). If a pattern itself should change, change it deliberately and update this guide in the same PR.