sshctl/CONTRIBUTING.md

Contributing

Development Setup

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:

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

# 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:

make release