From 7210a30f2c73119d4572ccf26fef47220614495d Mon Sep 17 00:00:00 2001 From: Anthon Linton <273287886+thetondj-gif@users.noreply.github.com> Date: Tue, 27 Oct 2026 00:41:28 +0000 Subject: [PATCH] doc: rewrite CONTRIBUTING.md for Rust CLI Remove obsolete Python setup, dead Dev-AI/dev links, and pytest instructions. Add cargo build, cargo test, and cargo clippy guidance matching README.md, document test locations (tests/cli.rs, unit tests in src), and streamline PR process. Fixes #12 --- CONTRIBUTING.md | 257 ++++++++++-------------------------------------- 1 file changed, 50 insertions(+), 207 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b6576f0ba..79d93e80d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,241 +1,84 @@ +# Contributing to Hanzo CLI -# Contributing to the Project - -We welcome contributions in the form of bug reports, feature requests, -and pull requests (PRs). This document describes how you can -contribute. +Thank you for contributing to the Hanzo CLI! We welcome contributions in the form of bug reports, feature requests, documentation improvements, and pull requests. ## Bug Reports and Feature Requests -Please submit bug reports and feature requests as GitHub issues. This -helps us to keep track of them and discuss potential solutions or -enhancements. - -## LLM Benchmark Results - -Contributions of -[LLM benchmark results](https://dev.chat/docs/leaderboards/) -are welcome! -See the -[benchmark README](https://github.com/Dev-AI/dev/blob/main/benchmark/README.md) -for information on running dev's code editing benchmarks. -Submit results by opening a PR with edits to the -[benchmark results data files](https://github.com/Dev-AI/dev/blob/main/dev/website/_data/). - - -## Pull Requests - -We appreciate your pull requests. For small changes, feel free to -submit a PR directly. If you are considering a large or significant -change, please discuss it in a GitHub issue before submitting the -PR. This will save both you and the maintainers time, and it helps to -ensure that your contributions can be integrated smoothly. - -## Licensing - -Before contributing a PR, please review our -[Individual Contributor License Agreement](https://dev.chat/docs/legal/contributor-agreement.html). -All contributors will be asked to complete the agreement as part of the PR process. - -## Setting up a Development Environment - -### Clone the Repository - -``` -git clone https://github.com/Dev-AI/dev.git -cd dev -``` - -### Create a Virtual Environment +Please submit bug reports and feature requests via GitHub Issues: +https://github.com/hanzoai/cli/issues -It is recommended to create a virtual environment outside of the repository to keep your development environment isolated. +When filing an issue, please include: +- A clear, descriptive title +- Steps to reproduce the problem +- Expected vs. actual behavior +- Your OS and CLI version (`hanzo --version`) -#### Using `venv` (Python 3.9 and later) - -``` -python -m venv /path/to/venv -``` +## Development Setup -### Activate the Virtual Environment +The Hanzo CLI is built in Rust (edition 2021). You will need a working Rust toolchain (Rust 1.75+ recommended) installed via [rustup](https://rustup.rs). -#### On Windows +### 1. Clone the Repository +```bash +git clone https://github.com/hanzoai/cli.git +cd cli ``` -/path/to/venv/Scripts/activate -``` - -#### On Unix or macOS - -``` -source /path/to/venv/bin/activate -``` - -### Install the Project in Editable Mode - -This step allows you to make changes to the source code and have them take effect immediately without reinstalling the package. - -``` -pip install -e . -``` - -### Install the Project Dependencies - -``` -pip install -r requirements.txt -``` - -For development, at least install the development dependencies: - -``` -pip install -r requirements/requirements-dev.txt -``` - -Consider installing other optional dependencies from the `requirements/` directory, if your development work needs them. - -Note that these dependency files are generated by `./scripts/pip-compile.sh` and then committed. See [Managing Dependencies](#managing-dependencies). - -### Install Pre-commit Hooks (Optional) - -The project uses pre-commit hooks for code formatting and linting. If you want to install and use these hooks, run: - -``` -pre-commit install -``` - -This will automatically run the pre-commit hooks when you commit changes to the repository. -Now you should have a fully functional development environment for the Dev project. You can start making changes, running tests, and contributing to the project. +### 2. Build from Source -### Handy Opinionated Setup Commands for MacOS / Linux - -Here's an example of following the setup instructions above, for your copy/paste pleasure if your system works the same. Start in the project directory. - -``` -python3 -m venv ../dev_venv \ - && source ../dev_venv/bin/activate \ - && pip3 install -e . \ - && pip3 install -r requirements.txt \ - && pip3 install -r requirements/requirements-dev.txt +```bash +cargo build ``` -### Running Tests +This builds the `hanzo` binary in `target/debug/hanzo`. -Just run `pytest`. +### 3. Run Linter -### Building the Docker Image - -The project includes a `Dockerfile` for building a Docker image. You can build the image by running: - -``` -docker build -t dev -f docker/Dockerfile . +```bash +cargo clippy --bin hanzo ``` -### Building the Documentation - -The project's documentation is built using Jekyll and hosted on GitHub Pages. To build the documentation locally, follow these steps: - -1. Install Ruby and Bundler (if not already installed). -2. Navigate to the `dev/website` directory. -3. Install the required gems: - ``` - bundle install - ``` -4. Build the documentation: - ``` - bundle exec jekyll build - ``` -5. Preview the website while editing (optional): - ``` - bundle exec jekyll serve - ``` - -The built documentation will be available in the `dev/website/_site` directory. - -## Coding Standards - -### Python Compatibility +## Running Tests -Dev supports Python versions 3.9, 3.10, 3.11, and 3.12. When contributing code, ensure compatibility with these supported Python versions. +The test suite consists of unit tests and integration tests that run the compiled binary: -### Code Style +### Run Full Test Suite -The project follows the [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide for Python code, with a maximum line length of 100 characters. Additionally, the project uses [isort](https://pycqa.github.io/isort/) and [Black](https://black.readthedocs.io/en/stable/) for sorting imports and code formatting, respectively. Please install the pre-commit hooks to automatically format your code before committing changes. - -### No Type Hints - -The project does not use type hints. - -### Testing - -The project uses [pytest](https://docs.pytest.org/en/latest/) for running unit tests. The test files are located in the `dev/tests` directory and follow the naming convention `test_*.py`. - -#### Running Tests - -To run the entire test suite, use the following command from the project root directory: - -``` -pytest +```bash +cargo test ``` -You can also run specific test files or test cases by providing the file path or test name: - -``` -pytest tests/basic/test_coder.py -pytest tests/basic/test_coder.py::TestCoder::test_specific_case -``` +### Test Locations -#### Continuous Integration +- **Integration tests:** `tests/cli.rs` runs the compiled CLI binary with real command-line arguments and exit codes, isolating state behind `--config `. +- **Unit tests:** Unit tests live alongside the implementation files, including `src/commands/product/tests.rs` and inline `#[cfg(test)]` modules throughout `src/`. -The project uses GitHub Actions for continuous integration. The testing workflows are defined in the following files: +### Run Specific Tests -- `.github/workflows/ubuntu-tests.yml`: Runs tests on Ubuntu for Python versions 3.9 through 3.12. -- `.github/workflows/windows-tests.yml`: Runs that on Windows +To run a single test or a subset of tests: -These workflows are triggered on push and pull request events to the `main` branch, ignoring changes to the `dev/website/**` and `README.md` files. +```bash +# Run a specific unit test by name +cargo test test_product_command -#### Docker Build and Test - -The `.github/workflows/docker-build-test.yml` workflow is used to build a Docker image for the project on every push or pull request event to the `main` branch. It checks out the code, sets up Docker, logs in to DockerHub, and then builds the Docker image without pushing it to the registry. - -#### Writing Tests - -When contributing new features or making changes to existing code, ensure that you write appropriate tests to maintain code coverage. Follow the existing patterns and naming conventions used in the `dev/tests` directory. - -If you need to mock or create test data, consider adding it to the test files or creating separate fixtures or utility functions within the `dev/tests` directory. - -#### Test Requirements - -The project uses `pytest` as the testing framework, which is installed as a development dependency. To install the development dependencies, run the following command: +# Run all integration tests in tests/cli.rs +cargo test --test cli -``` -pip install -r requirements-dev.txt +# Run a specific test inside tests/cli.rs +cargo test --test cli test_help ``` -### Managing Dependencies +## Pull Request Guidelines -When introducing new dependencies, make sure to add them to the appropriate `requirements.in` file (e.g., `requirements.in` for main dependencies, `requirements-dev.in` for development dependencies). Then, run the following commands to update the corresponding `requirements.txt` file: +1. **Discuss major changes:** For large architectural changes or new commands, please open an issue first to discuss the design before submitting code. +2. **Keep PRs focused:** Submit smaller, focused pull requests rather than large multi-purpose changes. +3. **Verify checks pass:** Before opening a PR, ensure that: + - Code builds without warnings: `cargo build` + - All tests pass: `cargo test` + - Clippy passes cleanly: `cargo clippy --bin hanzo` +4. **Follow commit conventions:** Write clear commit messages explaining what was changed and why. -``` -pip install pip-tools -./scripts/pip-compile.sh -``` +## Documentation & Community -You can also pass one argument to `pip-compile.sh`, which will flow through to `pip-compile`. For example: - -``` -./scripts/pip-compile.sh --upgrade -``` - -### Pre-commit Hooks - -The project uses [pre-commit](https://pre-commit.com/) hooks to automatically format code, lint, and run other checks before committing changes. After cloning the repository, run the following command to set up the pre-commit hooks: - -``` -pre-commit install -``` - -pre-commit will then run automatically on each `git commit` command. You can use the following command line to run pre-commit manually: - -``` -pre-commit run --all-files -``` +- Documentation: https://docs.hanzo.ai +- Homepage: https://hanzo.ai