Contributing

Contributing

Thanks for your interest in improving SimpleXisoDrive. This page describes how to report problems, propose changes, and submit code.

---

Ways to contribute

• Report bugs with console output and log files (see below).
• Suggest features through GitHub issues.
• Improve documentation in the docs/ folder.
• Submit code for fixes, format support, and performance work.
• Test with different ISO variants and report which ones work or fail.

Repository: https://github.com/purelogiccode/SimpleXisoDrive

---

Reporting bugs

Include as much of the following as possible:

1. Application version (shown in logs; currently 1.5.0).
2. Operating system and architecture (Windows x64/ARM64, Linux or macOS).
3. Mount backend version: Dokan on Windows, FUSE 3 / macFUSE on Linux and macOS.
4. The exact command line used.
5. The complete console output.
6. The newest logs/simplexisodrive-*.log file.
7. error.log and, if present, critical_error.log.
8. The image's size and origin (dump tool, format, and layout/packer, if known).

Never attach copyrighted game data; a description of the failure and log excerpt is enough.

---

Development setup

1. Install the .NET 10 SDK.

2. Clone the repository.

3. Build and test:

   dotnet build CSharp_SimpleXisoDrive.sln
   dotnet test CSharp_SimpleXisoDrive.sln

Dokan is only needed to run the application, not to build or test it.

See Building and Testing for details.

---

Code style

The project has a small, explicit style that reviewers expect:

Area	Convention
Namespaces	File-scoped (namespace SimpleXisoDrive;)
Nullable	Enabled; annotate nullability accurately
Usings	Implicit usings enabled; add explicit usings for non-implicit types
Types	var where the type is apparent
Fields	_camelCase for private instance fields; static readonly for shared state
Constants	PascalCase for constants used across members, UPPER_SNAKE is not used
Braces	Allman style; braces even for single statements
Comments	Only where they add value; prefer clear names and XML docs
Public API	XML documentation comments on classes, constructors, methods, and properties
Async	Async methods end in Async; fire-and-forget must be deliberate and documented
Exceptions	Catch at boundaries; log with Serilog rather than Console.WriteLine in services

The .editorconfig disables three analyzer rules (MA0004, MA0051, MA0015); everything else should build cleanly with the enabled Meziantou and Roslynator analyzers.

Safety rules for image access

• Keep all XDVDFS parsing inside XISOSharp; the application should only map virtual paths to the library's entry APIs and translate its exceptions.
• Keep image stream access serialized: rely on XisoExplorer's internal lock for path-based mounts and hold the volume's stream lock for embedded images.
• Treat offsets and lengths from the image as untrusted input; validate against the stream length.
• Never introduce a write path; the volume is read-only by design.

---

Tests

• Add or update xUnit tests for every behavioral change.
• Follow the naming convention MethodOrFeature_Scenario_ExpectedResult.
• Tests must not require Dokan, network access, admin rights, or a real ISO.
• Restore global state (current directory, temp files) in finally blocks.

Run before submitting:

dotnet build CSharp_SimpleXisoDrive.sln -c Release
dotnet test CSharp_SimpleXisoDrive.sln -c Release

The same commands run in GitHub Actions on every push and pull request (.github/workflows/ci.yml), and the release workflow re-runs the suite before packaging a release_* tag. See Building.

---

Pull request checklist

• The solution builds in Release with no new warnings.
• dotnet test passes.
• Public API changes have XML documentation.
• New behavior is covered by tests.
• Documentation in docs/ is updated when user-visible behavior changes.
• The version is bumped in every .csproj file only when preparing a release.
• No secrets, personal paths, or unrelated formatting changes are included.

Use clear commit messages that describe the change, for example:

Add XGD2 partition offset probing
Fix directory traversal aborting on empty names

---

Documentation contributions

The pages in docs/ are written in Markdown and drive both the GitHub wiki and the published documentation site. When editing:

• keep links wiki-style ([Installation](Installation)); the site layout rewrites them to the generated pages at runtime;
• update the side menus when adding or renaming a page: docs/_Sidebar.md (wiki) and docs/_data/navigation.yml (site);
• prefer precise, verifiable statements over marketing language;
• include exact error messages and file paths where relevant.

---

License and contributions

SimpleXisoDrive is licensed under GPL-3.0. By submitting a contribution, you agree that it is your own work and that it may be distributed under the same license.

---

Code of conduct

Be respectful and constructive. Reports and reviews should focus on the technical content. Harassment or abuse in issues or pull requests will not be tolerated.