distributed.camp
A Python port of the Invisible Internet Project (I2P)
1# Contributing to i2p-python
2
3Contributions are welcome. This document covers the basics.
4
5## Getting Started
6
7```bash
8git clone https://github.com/Bimo-Studio/i2p-python.git
9cd i2p-python
10python3 -m venv .venv
11source .venv/bin/activate
12pip install -e ".[dev]"
13```
14
15## Running Tests
16
17```bash
18python -m pytest tests/ -q
19```
20
21Tests are organized by package under `tests/`. Each `test_*` directory
22corresponds to a `src/` package.
23
24## Code Style
25
26- Python 3.11+
27- Type hints where practical
28- No line length limit enforced, but keep it reasonable
29- Follow existing patterns in the module you're modifying
30
31## Commit Messages
32
33This project uses [Conventional Commits](https://www.conventionalcommits.org/):
34
35```
36feat: add new tunnel pool selection strategy
37fix: correct nonce overflow in ChaCha20 counter
38docs: update SAM bridge usage examples
39test: add parity tests for ElGamal encryption
40```
41
42- `feat:` — new feature (bumps minor version)
43- `fix:` — bug fix (bumps patch version)
44- `feat!:` or `BREAKING CHANGE:` — breaking change (bumps major version)
45
46## Pull Requests
47
481. Fork the repo and create a feature branch
492. Write tests for new functionality
503. Ensure all tests pass
514. Use conventional commit messages
525. Open a PR against `main`
53
54Keep PRs focused. One feature or fix per PR.
55
56## Architecture
57
58The codebase is split into 15 packages under `src/`:
59
60| Package | Purpose |
61|---------|---------|
62| `i2p_crypto` | Cryptographic primitives |
63| `i2p_data` | Core data structures and I2NP messages |
64| `i2p_transport` | NTCP2 and SSU2 transports |
65| `i2p_tunnel` | Tunnel construction and management |
66| `i2p_netdb` | Network database (Kademlia DHT) |
67| `i2p_peer` | Peer connection management |
68| `i2p_router` | Full I2P router |
69| `i2p_sam` | SAM v3 bridge |
70| `i2p_streaming` | Streaming library |
71| `i2p_client` | Client API |
72| `i2p_kademlia` | Kademlia DHT implementation |
73| `i2p_util` | Shared utilities |
74| `i2p_stat` | Statistics collection |
75| `i2p_time` | Clock synchronization |
76| `i2p_apps` | Applications (I2PTunnel, desktop GUI) |
77
78## Security
79
80If you find a security vulnerability, **do not open a public issue**.
81See [SECURITY.md](SECURITY.md) for reporting instructions.
82
83## License
84
85By contributing, you agree that your contributions will be licensed
86under the MIT License.