# Contributing

## Development Setup

```bash
git clone https://src.panahifar.ir/ahp/sshctl.git
cd sshctl
python -m venv .venv
source .venv/bin/activate
make dev
```

## Code Quality

Before submitting a PR, run the full check suite:

```bash
make check
```

This runs lint, format-check, typecheck, and tests in sequence.

## Code Conventions

- **Python 3.13+** — use modern typing (`str | None`, `list[str]`, etc.)
- **`from __future__ import annotations`** — required in every file
- **`@dataclass`** — preferred for data models
- **Imports** — lazy imports in CLI layer, top-level imports in domain modules
- **Async** — `asyncio` with `Semaphore` for all network operations
- **Testing** — pytest with `tmp_path` for files, `pytest.raises` for exceptions
- **Type annotations** — required on all public functions

## Project Structure

```
src/sshctl/
  cli/          CLI interface (app.py)
  core/         Shared foundation (models, exceptions, config, logging)
  config/       SSH config lifecycle (parser, generator, resolver, validator)
  operations/   Active operations (checker, executor)
  export/       Export/integration (exporter, inventory, permissions)
```

## Pull Request Process

1. Ensure `make check` passes
2. Add tests for new functionality
3. Update CHANGELOG.md
4. Update README.md if user-facing changes

## Release Process

```bash
# Update version in src/sshctl/core/_version.py
# Update CHANGELOG.md
git commit -m "Release v0.x.y"
git tag v0.x.y
git push origin main --tags
# CI builds and publishes wheel + deb
```

Or manually:

```bash
make release
```