Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
188 lines (143 loc) · 6.92 KB

CONTRIBUTING.md

File metadata and controls

188 lines (143 loc) · 6.92 KB

Contributing to Pilot Protocol

Thank you for your interest in contributing to Pilot Protocol. This document covers guidelines and instructions for contributing.

Getting Started

Prerequisites

  • Go 1.21 or later
  • Git

Setup

git clone git@github.com:TeoSlayer/pilotprotocol.git
cd pilotprotocol
go build ./...

Running Tests

go test -parallel 4 -count=1 ./tests/

The -parallel 4 flag is required. Unlimited parallelism exhausts ports and sockets, causing dial timeouts and flaky failures.

Integration Tests

Full integration tests against a real test network are available using Docker:

cd tests/integration
make test                # Run all integration tests
make test-cli            # Run CLI tests only
make test-sdk            # Run Python SDK tests only

These tests validate the entire stack (Go binaries + Python SDK) against agent-alpha, a public demo agent running on the network. See tests/integration/README.md for details.

Project Structure

cmd/                    # Binary entry points
  daemon/               # Core network daemon
  pilotctl/             # CLI tool
  rendezvous/           # Combined registry + beacon server
  gateway/              # IP-to-Pilot bridge
  registry/             # Standalone registry (split deployment)
  beacon/               # Standalone beacon (split deployment)
  nameserver/           # DNS-equivalent nameserver (WIP)
pkg/                    # Library packages
  protocol/             # Wire format, addresses, headers, checksums
  daemon/               # Daemon core: connections, ports, transport, services
  driver/               # Client-side IPC driver (Unix socket)
  registry/             # Registry server + client + replication
  beacon/               # STUN-based NAT traversal
  gateway/              # TCP-to-Pilot proxy bridge
  secure/               # X25519 + AES-256-GCM encrypted connections
  dataexchange/         # Typed frame protocol (port 1001)
  eventstream/          # Pub/sub event broker (port 1002)
  tasksubmit/           # Task lifecycle with polo score (port 1003)
  nameserver/           # DNS-equivalent name resolution (WIP)
  config/               # JSON config file support
  logging/              # Structured logging setup (slog)
examples/               # Example applications
  echo/                 # Standalone echo server (now built into daemon)
  webserver/            # HTTP server over Pilot port 80
  dataexchange/         # Data exchange client
  eventstream/          # Event stream pub/sub client
  client/               # Basic client example
  httpclient/           # HTTP client over Pilot
  secure/               # Secure connection example
  config/               # Config file example
sdk/                    # Language SDKs
  python/               # Python SDK (see sdk/python/CONTRIBUTING.md)
  cgo/                  # CGO bindings
tests/                  # Integration tests (39 test files, 202+ passing)
docs/                   # Documentation
  SPEC.md               # Wire specification
  WHITEPAPER.pdf        # Protocol whitepaper (LaTeX source: WHITEPAPER.tex)
  SKILLS.md             # Agent skill definition

Contributing to the Python SDK

See the Python SDK Contributing Guide.

Quick start for Python SDK development:

cd sdk/python
python -m venv venv
source venv/bin/activate
pip install -e .[dev]
make test

How to Contribute

Reporting Issues

  • Check existing issues first to avoid duplicates
  • Include Go version, OS, and steps to reproduce
  • For test failures, include the full test output with -v flag

Pull Requests

  1. Fork the repository
  2. Create a feature branch from main
  3. Write your changes
  4. Add or update tests as needed
  5. Ensure all tests pass: go test -parallel 4 -count=1 ./tests/
  6. Ensure the project builds: go build ./...
  7. Submit a pull request with a clear description

Code Style

  • Follow standard Go conventions (gofmt, go vet)
  • Keep functions focused and small
  • Use slog for structured logging (not log or fmt.Printf for runtime output)
  • Error messages should be lowercase without trailing punctuation
  • Use the existing patterns in the codebase as reference

Testing Guidelines

  • All new features should have integration tests in tests/
  • Tests use the TestEnv helper (tests/testenv.go) which spins up in-process daemons
  • If your feature adds a built-in service or uses a well-known port, add a Disable* config field and use it in tests that bind those ports via driver
  • Use t.Parallel() in all test functions
  • Use timeouts on all blocking operations (channels, reads) to prevent hung tests
  • Prefer table-driven tests for multiple input variations

Architecture Notes

  • The daemon is the only process agents need to run. Built-in services (echo, data exchange, event stream, task submit) start automatically
  • All daemon interaction goes through the IPC socket (Unix domain socket). The driver package provides the client side; the daemon/ipc.go provides the server side
  • The transport layer implements TCP-like semantics: SYN/ACK handshake, sliding window, SACK, congestion control (AIMD), flow control, Nagle, retransmission
  • Security is layered: tunnel-level encryption (all traffic between two daemons) and connection-level encryption (port 443, per-connection X25519 + AES-GCM)
  • Trust is privacy-first: nodes are private by default, mutual handshake required, signed with Ed25519

Commit Messages

  • Use imperative mood: "Add feature" not "Added feature"
  • First line: concise summary under 72 characters
  • Body (optional): explain the why, not just the what

Areas for Contribution

  • Python SDK: Improve the Python SDK, add examples, enhance documentation (see sdk/python/CONTRIBUTING.md)
  • Nameserver (port 53): DNS-equivalent name resolution is WIP and needs implementation
  • Tests: expanding coverage, especially for edge cases in transport and security
  • Documentation: improving examples, tutorials, architecture docs
  • Performance: profiling and optimizing the transport layer
  • Platform support: testing on different OS/architectures
  • Language SDKs: Create SDKs for other languages (JavaScript, Rust, Java, etc.)

License

By contributing to Pilot Protocol, you agree that your contributions will be licensed under the GNU Affero General Public License v3.0.

Development

Running tests

make test              # Run all tests
make coverage          # Run tests with coverage and update badge
make coverage-html     # Generate HTML coverage report

Pre-commit hooks

Set up automatic code quality checks before each commit:

./scripts/setup-hooks.sh

This installs a git hook that automatically runs:

  • go fmt - Code formatting
  • go vet - Static analysis
  • go test - All tests
  • Coverage badge update

To skip the hook temporarily: git commit --no-verify