Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
114 lines (89 loc) · 4.71 KB

CONTRIBUTING.md

File metadata and controls

114 lines (89 loc) · 4.71 KB

Contributing to cli-plugins

We welcome and appreciate all contributions to the cli-plugins project! By participating, you agree to uphold our Code of Conduct.

This guide outlines the development workflow and how you can get involved.

Table of Contents

How to Contribute

Reporting Bugs

If you find a bug, please open an issue on our GitHub Issues page and include:

  • A clear and concise description of the bug.
  • Steps to reproduce the behavior.
  • Expected behavior.
  • Actual behavior.
  • Screenshots or error messages if applicable.
  • Your environment (OS, Python version, uv version).

Suggesting Features

We love new ideas! If you have a feature request, please open an issue on our GitHub Issues page and include:

  • A clear and concise description of the feature.
  • The problem it solves.
  • Any alternative solutions you've considered.

Contributing Code

  1. Fork the repository on GitHub.
  2. Clone your forked repository to your local machine. 
    git clone https://github.com/YOUR_USERNAME/cli-plugins.git
cd cli-plugins
  3. Setup your development environment as described in Development Setup.
  4. Create a new branch for your feature or bug fix. 
    git checkout -b feature/your-feature-name
# or
git checkout -b bugfix/fix-bug-description
  5. Make your changes. Ensure your code adheres to our Code Style Guidelines.
    • For changes to the crawler (src/crawler/) or generator (src/generator/plugin_generator.py)
    • For adding a new CLI configuration, edit config.yaml as described in the existing documentation.
  6. Run tests: uv run pytest tests/ -v to ensure everything is working as expected and all tests pass.
  7. Test with a real CLI: uv run cli-crawler <cli> -o output/<cli>.json --raw -v to verify your changes.
  8. Generate a plugin: uv run generate-plugin output/<cli>.json and verify the output.
  9. Commit your changes using our Commit Message Guidelines. 
    git commit -m "feat: Add new feature"
  10. Push your branch to your forked repository. 
    git push origin feature/your-feature-name
  11. Open a Pull Request against the main branch of the original repository. Provide a clear description of your changes, reference any related issues, and ensure all tests pass.

Development Setup

  1. Clone the repository: 
    git clone https://github.com/nsalvacao/cli-plugins.git
cd cli-plugins
  2. Install dependencies (including dev tools like Ruff/Black) using uv: 
    uv sync
uv sync --group dev  # install dev dependencies (linting/formatting tools)

Code Style Guidelines

We adhere to the following code style and quality standards:

  • Python 3.11+ with type hints
  • No external dependencies for crawler or generator (stdlib only)
  • Keep files under 500 lines
  • Tests go in tests/, never in root
  • We use linters and formatters to maintain code consistency. Ensure your code passes all checks before submitting a PR.
    • Run uv run ruff check . for linting.
    • Run uv run ruff format . for formatting.
    • These tools are installed as part of the dev dependency group via uv sync --group dev.

Commit Message Guidelines

We follow the Conventional Commits specification. This helps us maintain a clear commit history and automate releases.

Examples:

  • feat: Add new CLI configuration for new-tool
  • fix: Correct parsing of --help output for tool-x
  • docs: Update contributing guidelines with community focus
  • refactor: Improve crawler performance

Community & Ecosystem

We are committed to building a friendly and inclusive community around cli-plugins.

  • Be Respectful: Always adhere to our Code of Conduct.
  • Engage: Participate in discussions, provide feedback on issues and pull requests, and help others.
  • Share: If you build something cool with cli-plugins (e.g., a new plugin, a useful script, or an integration), share it with the community!
  • Support: Help us improve by reporting bugs, suggesting features, and contributing code.