Skip to content

contributing

Jump to bottom
github-actions[bot] edited this page Nov 8, 2026 · 8 revisions

Contributing

Thanks for considering a contribution! This project is a byte-faithful port of extract-xiso.c (reference build 202609111233), and that goal shapes every rule below.

Workflow

  1. Fork the repository and clone your fork.
  2. Create a feature branch: git checkout -b feat/my-change.
  3. Open CSharp_XISOSharp.sln in Visual Studio, or work from the CLI.
  4. Build and test before starting: 
    dotnet build
dotnet test XISOSharp.Tests
  5. Make your change with tests (see below).
  6. Push and open a pull request against master (the repo's branch; CI also accepts main-named forks for the workflow triggers).

Code style

  • Follow the analyzers and formatting rules in .editorconfig (Meziantou.Analyzer + Roslynator are wired into every project; the build must stay at 0 warnings).
  • The library multi-targets net8.0/net9.0/net10.0 — do not use APIs that are unavailable on net8.0.
  • XML documentation is mandatory on every new public API member of the XISOSharp library — the package generates the doc file and package validation runs in strict mode. (App/harness projects need no doc file; document their public surface only where it aids maintenance.)
  • Prefer the existing idioms: FileStreamOptions, BinaryPrimitives little-endian helpers, Span<byte> for header I/O, thread-static scratch buffers.

Pull request guidelines

  • Keep changes focused and minimal; one logical change per PR.
  • Every functional change must come with unit or integration tests.
  • Verify the full suite passes and the solution builds with 0 warnings: 
    dotnet build CSharp_XISOSharp.sln -c Release
dotnet test XISOSharp.Tests -c Release
  • For behavior-affecting changes, run the reference comparison (the oracle-gated interop tests plus the battle harness, see Testing).
  • Update documentation when user-facing behavior changes (CLI flags, public API, format handling) - this wiki lives in docs/.
  • Contributions are licensed under the MIT license of the project.

Definition of done

For every item that changes code:

  • Library API implemented; CLI and GUI wired where applicable.
  • Unit + integration + parity/interop + CLI contract tests added.
  • Synthetic fixtures only; no copyrighted game data and no GPL binaries.
  • Docs, READMEs and release notes updated in the same change.
  • Full suite green on the supported TFM matrix (net8.0/net9.0/net10.0); dotnet format clean; InspectCode 0 warnings; trim/AOT analyzers clean.
  • dotnet pack succeeds with package validation.
  • No deletion of files under bin/Release, publish* or release zips (see AGENTS.md).
# Full build + tests
dotnet build CSharp_XISOSharp.sln -c Release -m:1
dotnet test XISOSharp.Tests/XISOSharp.Tests.csproj -c Release

# Formatting and packaging
dotnet format whitespace CSharp_XISOSharp.sln --verify-no-changes --no-restore
dotnet pack XISOSharp/XISOSharp.csproj -c Release -o artifacts

# AOT, fuzz and benchmarks
dotnet publish XISOSharp.AotSmoke/XISOSharp.AotSmoke.csproj -c Release -r linux-x64
dotnet run --project XISOSharp.Fuzz -c Release -- --seconds 60
dotnet run --project XISOSharp.Benchmarks -c Release -- --filter "*EndToEnd*"

Distribution verification commands are in Building.

Compatibility discipline

The original conversion followed a strict rule: never proceed to the next step without a 100% hash match against the reference C tool. Preserve that spirit:

  • Output ISOs must stay byte-identical to extract-xiso (reference build 202609111233) for the same input.
  • Do not "improve" AVL rebalancing or directory layout — the existing behavior is the compatibility contract.
  • When changing the reader, keep llCompat semantics intact (legacy vs. optimized layouts).
  • New features must be additive (new flags, new optional parameters, new methods) so existing behavior is unchanged.

Areas to contribute

Good starting points:

  • Completed work and history are in Project History; the former missing-feature plan has been retired now that all tracked items are implemented.
  • docs/ improvements - accuracy passes, examples, screenshots.
  • Test coverage: sustain >85% line coverage on XisoReader.cs, XisoWriter.cs, AvlTree.cs (currently 94.2% / 89.6% / 100% - see Testing); new code paths need tests, and new corruption shapes belong in XisoCorruptionResilienceTests.cs.
  • Batch-script edge cases for -d on Windows.

See also: Building · Testing · Troubleshooting

Clone this wiki locally