Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
60 lines (51 loc) · 2.64 KB

CONTRIBUTING.md

File metadata and controls

60 lines (51 loc) · 2.64 KB
Raw

Contributing Effects

Thanks for contributing to the xfetch effects ecosystem. This repository contains official effects and the reference implementations for building new ones.

Workflow

  1. Fork the repository and create a feature branch.
  2. Create a new effect crate under effects/<name>/.
  3. Add it to the workspace members in Cargo.toml.
  4. Run cargo test --workspace and cargo build --workspace.
  5. Document the effect in its own README.md (build, install, config, protocol) and add it to the table in README.md.
  6. Add a short entry to the effect's CHANGELOG.md.
  7. Open a pull request with usage details and any required dependencies. PRs that do not compile or fail tests are rejected.

Effect Rules

  • Use the binary naming convention xfetch-effect-<name>.
  • Keep effects focused on a single visual idea.
  • Write errors to stderr and exit with a non-zero status on failure.
  • Never break ANSI escape sequences. The rendered lines carry colors and icons; tokenize them with xfetch-effects-lib (tokenize/rebuild) and only transform the visible characters. A partial escape sequence makes the terminal interpret it and leaks garbage onto the screen — this is enforced by the effects-lib tests.
  • Every effect MUST have a runtime limit. Wrap all work in with_timeout (from xfetch_effect_api) with a const BUDGET that fits the work. An effect without a timeout is rejected: it could hang xfetch forever.
  • Prefer deterministic output (seeded) so tests are stable.
  • The last frame should reach the final (unmodified) content.
  • Prefer stable, actively maintained dependencies and keep them minimal.

Protocol Guide

The wire protocol (xfetch-effect-api) is documented in effect-sdk.md and the protocol reference. Shared ANSI-safe helpers live in effects/effects-lib — reuse them instead of reimplementing the tokenizer.

Code of Conduct

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