Adapter Onboarding Checklist

View Source

Use this checklist when adding a new Jido.VFS.Adapter.* module or when changing adapter metadata semantics.

1. Metadata callbacks (required)

  • Implement unsupported_operations/0.
  • Implement versioning_module/0.
  • Return stable values:
    • unsupported_operations/0 returns a list of operation atoms.
    • versioning_module/0 returns a module that implements Jido.VFS.Adapter.Versioning, or nil.

2. Error semantics

  • Public API paths must return :ok, {:ok, value}, or {:error, %Jido.VFS.Errors.*{}}.
  • Unsupported paths must return %Jido.VFS.Errors.UnsupportedOperation{operation, adapter}.
  • Map backend/platform-specific failures to typed errors (FileNotFound, PermissionDenied, AdapterError, etc.).

3. Contract and metadata tests

  • Add/extend adapter tests for happy paths and representative failure paths.
  • Add/extend tests that exercise metadata callbacks through Jido.VFS.supports?/2 and versioning calls.
  • Ensure the adapter remains covered by metadata contract tests in test/jido_vfs/adapter/metadata_contract_test.exs.

4. Docs and discoverability

  • Update README.md and/or CONTRIBUTING.md if adapter behavior or prerequisites changed.
  • Keep dependency examples and adapter capability notes aligned with the implementation.

5. Release gates