Development and AI contribution guide

Orient before editing

Read Architecture, the relevant public type's XML comments, and its tests. Trace behavior from GitClient through GitSnapshotAcquirer rather than assuming this is a wrapper around a Git executable. The solution currently includes the library, two samples, and documentation; both test projects are outside the solution.

Source files are in CODE.Git.Client and its Internal subfolder; tests are in CODE.Git.Client.Tests and CODE.Git.Client.IntegrationTests.

Build and automated tests

From the repository root:

dotnet build CODE.Git.slnx
dotnet test CODE.Git.Client.Tests/CODE.Git.Client.Tests.csproj
dotnet test CODE.Git.Client.IntegrationTests/CODE.Git.Client.IntegrationTests.csproj

Do not rely on dotnet test CODE.Git.slnx for coverage while the test projects are excluded. Library builds treat warnings as errors and emit a NuGet package. No special IDE or debugger settings should be needed.

Unit tests use FakeGitServer, RecordingHandler, generated in-memory protocol data, and committed binary packs. They need no Git executable or external Git server. Transport tests still perform DNS preflight, so do not assume that fake HTTP handlers eliminate every DNS dependency. Filesystem tests use temporary directories; the Windows reparse-point test creates a junction without requiring symlink developer mode.

Live provider tests

External tests skip unless GITCLIENT_TEST_URLS is set. Use semicolon-separated HTTPS URLs to repositories you are authorized to access:

$env:GITCLIENT_TEST_URLS = 'https://github.com/octocat/Hello-World.git'
dotnet test CODE.Git.Client.IntegrationTests/CODE.Git.Client.IntegrationTests.csproj

For an authenticated run, supply GITCLIENT_TEST_TOKEN through your secret-management workflow and optionally set GITCLIENT_TEST_USER (defaults to git). The test uses Basic authentication when a token exists. One credential pair applies to every configured URL; use separate runs when endpoints need different credentials. Never commit token values or print them in logs. Remove session variables afterward when appropriate:

Remove-Item Env:GITCLIENT_TEST_URLS -ErrorAction SilentlyContinue
Remove-Item Env:GITCLIENT_TEST_USER -ErrorAction SilentlyContinue
Remove-Item Env:GITCLIENT_TEST_TOKEN -ErrorAction SilentlyContinue

The provider test lists a tree, chooses one regular/executable file, fetches it at the pinned commit, consumes the stream, and checks callback counts. It expects a nonempty repository with at least one supported file. It does not test all provider features or Bearer login. Missing shallow/filter capabilities or selective OID refusal should remain explicit failures.

Pack fixtures

Committed fixtures live in Fixtures: base objects, OFS deltas, REF deltas, and forward REF deltas. Regenerate with either script, from the repository root:

pwsh -File CODE.Git.Client.Tests/Fixtures/generate.ps1
python CODE.Git.Client.Tests/Fixtures/generate.py

Use PowerShell 7 or Python 3 respectively. Review binary changes and rerun pack tests after regeneration. Keep malformed-input and budget tests when changing parsers; successful snapshots alone do not establish parser correctness.

Contribution rules

Follow applicable AGENTS.md instructions and read C:/Users/megge/.codex/standards/csharp.md before creating, modifying, or reviewing C#. Keep hand-written classes in their main code files; do not introduce partial classes unless explicitly requested. Honor repository formatting, including underscore-prefixed private instance fields, one statement per line, inferred locals, collection expressions, and target-typed construction where applicable.

Fix expected behavior in application code so it works with standard IDE/debugger settings while keeping unexpected failures visible. Maintain cancellation, stream ownership, serialized callbacks, explicit unsupported-operation failures, bounded resource accounting, and caller ownership of injected HTTP clients. Do not add automatic full-fetch fallbacks or retry side-effecting callbacks without an intentional contract change.

When changing behavior, update its documentation and use relevant existing tests or add meaningful coverage. Preserve public documentation filenames, path casing, URL patterns, and heading anchors. Compare routes and anchors before and after edits; add new URLs for new topics rather than renaming established ones. The root README is also packaged into the library, so keep its examples aligned with the implementation.

Authentication already exists; see Authentication. Richer login/token lifecycle support would be new work. Document current capability separately from planned behavior, and do not claim live provider verification unless those tests actually ran.

Publishing through Lorekeeper

Docs/toc.json contains the complete Git section to merge into the site's _toc.json, before CODE Editor. Preserve its existing link and slug values, including the DevProcess landing-page slug and Process child slugs. Copy the documentation into the site's DevProcess/GitClient source folder. The landing-page source must be published as readme.md to match the supplied TOC exactly; the repository keeps its existing README.md filename. Do not rename the public route to compensate for filename casing.

Page navigation uses site-root URLs from the TOC, rather than source .md filenames. Source-code links point to the Azure DevOps repository browser and require repository access. Keep source links synchronized if repository locations change. This documentation targets the site's root URL; an installation beneath a URL prefix must apply that prefix consistently during import.

The component and clone-flow diagrams are embedded SVGs in Architecture.md to avoid dependence on image-serving routes or client-side diagram scripts. Their SVG title/description elements provide accessible text, and their CSS and marker IDs are scoped to each diagram. Keep the embedded SVGs synchronized with the editable assets Images/Architecture.svg and Images/CloneFlow.svg. The full-size source links open those assets in the repository browser. Copy Images with the documentation so the source assets remain available to maintainers.

The architecture page requires inline SVG support but does not require Mermaid. Its diagrams are static and do not depend on JavaScript initialization. The current TOC contract has been checked; live rendering and authenticated source-link access must be checked in the target Lorekeeper installation when it is available. No publication is performed by editing these files.