Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
126 lines (92 loc) · 4.08 KB

CONTRIBUTING.md

File metadata and controls

126 lines (92 loc) · 4.08 KB
Raw

Contributing to xfetch

Thank you for your interest in contributing to xfetch!


Code of Conduct

This project is open and welcoming. Be respectful, constructive, and collaborative. Harassment, trolling, and personal attacks are not tolerated.

How to Contribute

  1. Fork the repository on GitHub.
  2. Clone your fork locally.
  3. Create a feature branch (git checkout -b feature/my-change).
  4. Make your changes following the project conventions.
  5. Run cargo build and cargo test to verify everything works.
  6. Commit your changes with a clear message.
  7. Push to your fork.
  8. Open a Pull Request from your branch to the main repository.

Contributing Plugins

Plugins are standalone executables that extend xfetch's functionality. To add a new plugin to the repository, follow this process:

1. Fork & Clone

Fork the repository on GitHub and clone your fork locally:

git clone https://github.com/YOUR_USERNAME/xfetch.git
cd xfetch
git checkout -b plugin-my-plugin

2. Create the Plugin Directory

Create your plugin under the plugins/ directory following the naming convention:

plugins/my-plugin/
├── Cargo.toml        # name = "xfetch-plugin-<name>"
├── README.md         # Documentation (HTML format, centered titles)
└── src/
    └── main.rs       # Plugin implementation

3. Implement the Protocol

Your plugin must communicate with xfetch via stdin/stdout using JSON:

  • Read exactly one JSON object from stdin.
  • Write exactly one JSON response object to stdout.
  • Write errors to stderr and exit with non-zero status on failure.

See plugins/docs/README.md for the full protocol specification.

4. Test Locally

# Build your plugin
cargo build --release --manifest-path plugins/my-plugin/Cargo.toml

# Install it locally
xfetch plugin install ./plugins/my-plugin

# Run xfetch and verify it appears
xfetch

5. Update Documentation

  • Add a README.md for your plugin documenting its features, configuration, and output.
  • Add an entry for your plugin in plugins/README.md under the "Available Plugins" table.

6. Commit and Push

git add plugins/my-plugin/ plugins/README.md
git commit -m "feat(plugins): add my-plugin"
git push origin plugin-my-plugin

7. Open a Pull Request

Open a PR from your branch to the main repository's main branch. In the PR description, include:

  • A brief description of what your plugin does.
  • The kind of plugin (info_provider or logo_animation).
  • Any dependencies required (e.g., curl, docker CLI).
  • Screenshot or example output (optional but recommended).

Code Standards

  • Use cargo build and cargo test before submitting.
  • Follow existing code style — no trailing whitespace, consistent indentation.
  • Write all code, comments, and documentation in English.
  • Keep plugins focused on a single responsibility.
  • Minimize dependencies to keep build times fast.
  • Do not add network calls or file I/O to animation plugins — they should be pure transformations.

Reporting Issues

Open an issue on GitHub with a clear description of the problem, steps to reproduce, and your environment (OS, terminal emulator, xfetch version).

License

By contributing, you agree that your contributions will be licensed under the project's LICENSE.