CONTRIBUTING.md

Contributing to the API

Thanks for contributing to the xfetch SDK ecosystem. This repository hosts the protocol crates every plugin, extension and effect builds against:

• crates/plugin-api — xfetch-plugin-api: info providers and logo animations
• crates/extension-api — xfetch-extension-api: config providers
• crates/effect-api — xfetch-effect-api: intro effects

Workflow

1. Fork the repository and create a feature branch.
2. Make your changes in the relevant crate under crates/<name>/.
3. Run the full CI locally before opening the PR: bash scripts/ci.sh (Linux/macOS) or ./scripts/ci.ps1 (Windows), plus bash scripts/ci-windows.sh for the Windows cross-target check. PRs that fail CI are rejected.
4. Document protocol changes in docs/ (protocol.md, the matching *sdk.md, timeouts.md).
5. Add an entry to CHANGELOG.md.
6. Open a pull request.

API Rules

• Semver. Breaking protocol changes bump the major version of the affected crate; additive changes (new fields, new constants) must remain backward compatible with the wire format.
• Keep crates platform-neutral. The SDK types are plain serde structs — no OS-specific code, no runtime dependencies beyond serde/serde_json unless strictly necessary.
• Every timeout helper stays in the API. with_timeout/TimedOut are the single place where process budgets are enforced; plugins, extensions and effects rely on them (see timeouts.md).
• Document every public item. These crates are the reference documentation for the ecosystem; public types and functions need doc comments with protocol semantics.
• Keep the wire protocol explicit. Use versioned constants (PROTOCOL_VERSION, kind constants) and never rely on runtime type names.
• Prefer stable, actively maintained dependencies and keep them minimal.

Code of Conduct

Be respectful, constructive, and collaborative. Harassment, trolling, and personal attacks are not tolerated.