Development Contributing

Contributing

Thanks for considering a contribution to FindRomCover. This page explains how to report issues, propose changes, and get your work merged.

Ways to contribute

• Report bugs with clear reproduction steps and log excerpts.
• Suggest features through GitHub Issues or Discussions.
• Improve documentation — every page is a Markdown file in docs/.
• Submit code for fixes, performance, or new features.

Reporting issues

Include:

1. FindRomCover version (visible in About).
2. Operating system and architecture (Windows x64/ARM64, Linux, or macOS).
3. Steps to reproduce.
4. Expected and actual behavior.
5. Relevant log entries (app<yyyyMMdd>.log in the per-user data folder — %LocalAppData%\FindRomCover on Windows — or the log window). Remove anything you do not want to share.
6. Whether AI Assist or the Google API was involved.

Development workflow

1. Fork the repository and create a branch:

   git checkout -b fix/short-description

2. Build and test:

   dotnet build CSharp_FindRomCover.sln
   dotnet test CSharp_FindRomCover.sln

   The test project targets net10.0-windows, so run the test suite on Windows even though the application itself builds and runs cross-platform.

3. Keep changes focused: one logical change per pull request.

4. Add or update tests for behavior changes.

5. Update documentation when user-visible behavior changes.

6. Open a pull request against master with a clear description.

Code style

• Follow .editorconfig and the existing formatting.
• Keep the build warning-free; the projects enable Meziantou, Roslynator, and Microsoft.CodeAnalysis analyzers.
• One top-level type per file.
• Prefer small, focused methods and clear names over comments.
• Use nullable reference types correctly; avoid suppressions.
• Name asynchronous methods with an Async suffix.
• Add XML documentation to public and internal members; the application project generates a documentation file.
• Never log secrets or personal data.

Tests

• New tests must be deterministic and independent of collection parallelization: xunit.runner.json disables parallel test collections, so do not rely on tests running concurrently.
• Do not depend on the real settings folder or the bug-report API; use the seams set up by TestBootstrap (SettingsManager.DefaultSettingsDirectoryOverride, ErrorLogger.SendToApiOverride).
• Every bug fix should come with a regression test. See Testing for the full conventions.

Commit messages

Use short, descriptive messages in the imperative mood, optionally with a conventional prefix:

fix: handle missing WebView runtime on startup
feat(ai): add Gemini provider
docs: document batch fill outcomes

Pull request checklist

• Build is warning-free.
• All tests pass.
• New behavior is covered by tests.
• User-facing changes are reflected in docs/ and, where relevant, README.md and WhatsNew.md.
• No secrets, tokens, or personal paths are committed.

Documentation contributions

The docs are built with MkDocs Material from docs/ and mirrored to the GitHub wiki by scripts/Sync-Wiki.ps1.

Preview locally:

pip install -r docs/requirements.txt
mkdocs serve

Guidelines:

• Use plain Markdown that renders both on the site and in the wiki (tables, lists, code fences, blockquotes).
• Link between pages with relative .md links; the wiki script rewrites them.
• Keep each page focused; add it to the nav in mkdocs.yml and to the sidebar structure in the sync script.
• Run mkdocs build --strict before submitting.

License

By contributing, you agree that your contributions are licensed under the GNU General Public License v3.0, the same license as the project. See License.

Related pages

• Building & Running
• Testing
• CI/CD