67 lines
1.6 KiB
Markdown
67 lines
1.6 KiB
Markdown
|
# 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
|
||
|
|
```
|