# Contributing to i2p-python

Contributions are welcome. This document covers the basics.

## Getting Started

```bash
git clone https://github.com/Bimo-Studio/i2p-python.git
cd i2p-python
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

## Running Tests

```bash
python -m pytest tests/ -q
```

Tests are organized by package under `tests/`. Each `test_*` directory
corresponds to a `src/` package.

## Code Style

- Python 3.11+
- Type hints where practical
- No line length limit enforced, but keep it reasonable
- Follow existing patterns in the module you're modifying

## Commit Messages

This project uses [Conventional Commits](https://www.conventionalcommits.org/):

```
feat: add new tunnel pool selection strategy
fix: correct nonce overflow in ChaCha20 counter
docs: update SAM bridge usage examples
test: add parity tests for ElGamal encryption
```

- `feat:` — new feature (bumps minor version)
- `fix:` — bug fix (bumps patch version)
- `feat!:` or `BREAKING CHANGE:` — breaking change (bumps major version)

## Pull Requests

1. Fork the repo and create a feature branch
2. Write tests for new functionality
3. Ensure all tests pass
4. Use conventional commit messages
5. Open a PR against `main`

Keep PRs focused. One feature or fix per PR.

## Architecture

The codebase is split into 15 packages under `src/`:

| Package | Purpose |
|---------|---------|
| `i2p_crypto` | Cryptographic primitives |
| `i2p_data` | Core data structures and I2NP messages |
| `i2p_transport` | NTCP2 and SSU2 transports |
| `i2p_tunnel` | Tunnel construction and management |
| `i2p_netdb` | Network database (Kademlia DHT) |
| `i2p_peer` | Peer connection management |
| `i2p_router` | Full I2P router |
| `i2p_sam` | SAM v3 bridge |
| `i2p_streaming` | Streaming library |
| `i2p_client` | Client API |
| `i2p_kademlia` | Kademlia DHT implementation |
| `i2p_util` | Shared utilities |
| `i2p_stat` | Statistics collection |
| `i2p_time` | Clock synchronization |
| `i2p_apps` | Applications (I2PTunnel, desktop GUI) |

## Security

If you find a security vulnerability, **do not open a public issue**.
See [SECURITY.md](SECURITY.md) for reporting instructions.

## License

By contributing, you agree that your contributions will be licensed
under the MIT License.