From 8cb270d98526a70ac02a49e7de1c5d905d075795 Mon Sep 17 00:00:00 2001 From: artem_tiupin <70763601+art-tapin@users.noreply.github.com> Date: Thu, 23 Jan 2025 15:17:07 +0000 Subject: [PATCH] docs: add developer_setup.md and update README to reference /docs (#44) - Created /docs/developer_setup.md with step-by-step instructions for setting up the development environment, installing uv and ruff, and configuring pre-commit hooks. - Updated README.md to include links to the new documentation in the /docs directory. - Clarified upstream documentation and mention internal Ansible Handbook --- README.md | 16 +++++ docs/developer_setup.md | 128 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 144 insertions(+) create mode 100644 docs/developer_setup.md diff --git a/README.md b/README.md index 827de40..2cce1d3 100644 --- a/README.md +++ b/README.md @@ -223,3 +223,19 @@ You can inspect the data sent with --dry-run attribute and provide your own inte # This will collect whole day of 2023-12-21 metrics-utility gather_automation_controller_billing_data --dry-run --since=2023-12-21 --until=2023-12-22 ``` + +## Developer Setup + +For developers contributing to this project, refer to the [Developer Setup Guide](./docs/developer_setup.md) for detailed instructions on setting up your local development environment, installing dependencies, and configuring pre-commit hooks. + +--- + +## Available Documentation + +Additional documentation is available in the `/docs` directory. This includes: + +- **Developer Setup**: [docs/developer_setup.md](./docs/developer_setup.md) + +Please note that this is the upstream documentation for the metrics-utility project. Additional internal downstream documentation, accessible only to the Ansible organization, is maintained separately in the [Ansible Handbook](https://github.com/ansible/handbook/tree/main/The%20Ansible%20Engineering%20Handbook/docs/AAP/Services/Metrics). + +As the project grows, more guides and references will be added to the `/docs` folder. \ No newline at end of file diff --git a/docs/developer_setup.md b/docs/developer_setup.md new file mode 100644 index 0000000..60f7c87 --- /dev/null +++ b/docs/developer_setup.md @@ -0,0 +1,128 @@ +# Developer Setup for `metrics-utility`: `ruff` + `uv` + +This document helps new contributors set up their local development environment for the `metrics-utility` repository. It covers installing required tools, configuring `uv`, and enabling a pre-commit hook that uses `ruff` for linting and formatting. + +--- + +## 1. Overview + +- **`uv`**: A Python virtual environment manager that simplifies dependency management. +- **`ruff`**: A fast Python linter and formatter. Ensures code adheres to style and best practices. + +The pre-commit hook leverages `ruff` (managed by `uv`) to automatically check and format your code whenever you run `git commit`. This helps maintain consistent code quality. + +--- + +## 2. Prerequisites + +- **Python 3.11+** installed on your system. +- **Git** installed for version control. +- **`pip`** or other package managers (e.g., `pipx`) for installing Python tools. + +--- + +## 3. Initial Setup + +1. **Clone the Repository**: + ```bash + git clone https://github.com/ansible/metrics-utility.git + cd metrics-utility + ``` + +2. **Install `uv` (if not installed)**: + ```bash + pip install uv + ``` + > **Note**: You may need to use `pip3` or run under a virtual environment if you have multiple Python versions. + +3. **Synchronize Dependencies**: + ```bash + uv sync + ``` + This command creates (or updates) the virtual environment defined by `pyproject.toml` and `uv.lock`. It installs all project dependencies, including `ruff`, `pytest`, `django-admin`, etc. + +4. **Verify Installations**: + ```bash + ruff --version + pytest --version + django-admin --version + pre-commit --version + ``` + If any command fails, run `uv sync` again or check your `uv` installation. + +--- + +## 4. Configuring Pre-commit Hooks + +1. **Install Pre-commit Hooks**: + ```bash + pre-commit install + ``` + This registers the hooks defined in `.pre-commit-config.yaml` so that every `git commit` triggers a lint/format check using `ruff`. + +2. **Test the Hook**: + 1. Create a test file with a simple linting error: + ```bash + echo "import os\n\nprint( 'Hello World' )" > test.py + ``` + 2. Stage and commit the file: + ```bash + git add test.py + git commit -m "Test pre-commit hook" + ``` + 3. The hook should **block** the commit, showing an error about the unused import or formatting issues. + +--- + +## 5. Fixing Linting Issues + +Depending on the project’s configuration: + +- **Manual Fix**: Remove unused imports or fix spacing. +- **Auto-fix with Ruff**: + ```bash + ruff format test.py + ``` + or + ```bash + ruff check test.py --fix + ``` + (Both commands achieve a similar result in the latest versions of Ruff.) + +After fixing, re-stage and commit again: +```bash +git add test.py +git commit -m "Fix linting issues" +``` +This time, the commit should succeed if all issues are resolved. + +--- + +## 6. Troubleshooting + +1. **`uv sync` Errors** + - Ensure Python 3.8+ is installed. + - Confirm you have the correct permissions to install packages. + +2. **`ruff` or `pre-commit` Not Found** + - Run `uv sync` again. + - Make sure your shell is set to use the environment from `uv`. + +3. **Hook Doesn’t Run** + - Check that `.pre-commit-config.yaml` references `ruff`. + - Re-run `pre-commit install`. + +4. **Bypassing Hooks** + - If you see developers bypassing hooks with `--no-verify`, note that the checks won’t run. For consistent code quality, discourage skipping hooks. + +--- + +## 7. Additional Resources + +- [Ruff Documentation](https://beta.ruff.rs/docs/) +- [Pre-commit Documentation](https://pre-commit.com/) +- [uv - GitHub Repository](https://github.com/astral-sh/uv) + +--- + +**That’s it!** You should now have a functioning development environment for `metrics-utility` with a pre-commit hook that catches lint and formatting issues via `ruff`. \ No newline at end of file