# Contributing to AsusRouter

This document describes the basics of contributing to the **AsusRouter** project.

_This file was auto-generated by **GitHub Copilot**, so minor adjustments may be needed. If you notice any issues or have suggestions for improvement, please feel free to submit a pull request or open an issue._

This project uses [uv](https://github.com/astral-sh/uv), [pre-commit](https://pre-commit.com/), and [Visual Studio Code](https://code.visualstudio.com/).

Please follow these guidelines for a smooth development experience.

---

## Development Environment Setup

1. **Clone the repository**

   ```sh
   git clone https://github.com/Vaskivskyi/asusrouter.git
   cd asusrouter
   ```

2. **Python Virtual Environment**

   - The project uses a `.venv` in the root directory.
   - Create it with:
     ```sh
     uv venv
     ```
   - In VS Code, select the interpreter from `.venv` via the Command Palette:
     `Python: Select Interpreter`.

3. **Install dependencies**

   - Install all dependencies (including dev and test) with:
     ```sh
     uv sync --all-groups
     ```

4. **Install pre-commit hooks**

   - Install pre-commit if not already installed:
     ```sh
     uv pip install pre-commit
     ```
   - Set up the hooks:
     ```sh
     pre-commit install
     ```
   - (Optional but recommended) Run on all files to check/fix the codebase:
     ```sh
     pre-commit run --all-files
     ```
   - **Note:** All commits will be checked by pre-commit hooks. You must fix any issues before committing.

5. **VS Code Workspace**

   - The `.vscode` folder is versioned and contains:
     - **Recommended extensions** (`extensions.json`)
     - **Editor settings** (`settings.json`)
     - **Common tasks** (`tasks.json`)
   - VS Code should prompt you to install recommended extensions on open.

---

## Recommended VS Code Extensions

These are listed in `.vscode/extensions.json` and will be suggested automatically:

- [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) (`charliermarsh.ruff`)
- [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) (`esbenp.prettier-vscode`)
- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) (`ms-python.python`)

---

## Recommended VS Code Settings

These are already included in `.vscode/settings.json`:

```jsonc
{
  "editor.formatOnSave": true,
  "[python]": {
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    },
    "editor.defaultFormatter": "charliermarsh.ruff"
  },
  "python.analysis.typeCheckingMode": "basic",
  "mypy-type-checker.args": ["--config-file=pyproject.toml"]
}
```

---

## Common Tasks

### Dependencies and development

You can run common development tasks from the VS Code Command Palette (`Ctrl+Shift+P` → "Run Task") or from the terminal:

- **Install requirements:**
  `uv sync`
- **Install dev requirements:**
  `uv sync --group dev`
- **Install test requirements:**
  `uv sync --group test`
- **Run tests:**
  Use the provided tasks in `.vscode/tasks.json` for different Python versions and test types.
- **Build package:**
  `uv build`

### Testing

You can run test suites using the pre-configured tasks. All the needed requirements for testing will be installed automatically.

- **Run Pytest / 3.{xx} / Unit:**
  Run all the unit tests for a corresponding Python version.
  Tasks include all the supported Python versions as per the `pyproject.toml` file.
- **Run Pytest / Devices:**
  Run all the device tests (tests on the raw / pre-configured data parsed from the actual devices).
  This test is run on the latest supported Python version.

---

## Code Style, Linting and Checks

- **Ruff** is used for linting and formatting.
  Code style is enforced automatically via pre-commit and VS Code settings.
- **mypy** is used for type checking.
- **pre-commit** is required for all commits.
  You must run `pre-commit install` after cloning (see setup above) to ensure all commits are checked locally.
  PRs that do not pass pre-commit checks will be blocked until they are fixed.

---

## Pull Requests

- Ensure all pre-commit hooks pass before pushing.
- Make sure your code is covered by tests.
- Describe your changes clearly in the PR description.

---

## Need Help?

If you have any questions or issues, please open an issue on [GitHub](https://github.com/Vaskivskyi/asusrouter/issues).

---
