How to contribute

SwiftSonic is open source under the MIT license. Issues and pull requests are welcome on the main repo: github.com/MathieuDubart/SwiftSonic.

Reporting issues

When opening an issue, include:

• SwiftSonic version (Package.swift resolution).
• Server software and version (Navidrome 0.52.0, Airsonic-Advanced, …).
• Swift toolchain.
• A minimal reproducer — ideally a 10-line snippet that fails.
• The full error: SwiftSonicError description, localizedDescription, and the underlying response if available.

For protocol bugs (the server returns X, the library decodes Y), please attach the raw HTTP response body. We will not chase reports without one.

Opening a pull request

• Branch from main.
• Match existing code style — no broad reformatting in feature PRs.
• Add tests for any behaviour change. Mock servers with URLProtocol are the established pattern.
• Update doc comments where the public API changes.
• Run the full test suite (swift test) before opening the PR.

Spec-compliance rule

The single hard rule for new features:

If it is not in the Subsonic or OpenSubsonic specification, it does not belong in SwiftSonic.

Concretely, that rules out:

• Endpoints that only one server implements.
• Headers, parameters, or response fields invented by a single vendor.
• Workarounds for a specific server’s bug — those go in the consuming app, not the library.

We are happy to accept new endpoints from the OpenSubsonic spec as soon as they’re standardized.

Reference

TODO: link the actual CONTRIBUTING.md from the SwiftSonic repo once it’s added or formalized. For now, the rules above are authoritative for this site.