CONTRIBUTING.md

Contributing to OnionSpy

Thanks for contributing. This guide keeps contributions consistent and reviewable.

Prerequisites

• Python 3.13+
• Tor daemon available locally
• Optional: Ollama and MongoDB for full feature testing

Local Setup

Windows:

setup.bat

Linux/macOS:

bash setup.sh

Then run:

python main.py

Contribution Workflow

1. Fork and create a focused branch.
2. Keep changes scoped to one feature/fix.
3. Update docs when behavior or commands change.
4. Submit PR with clear summary and testing notes.

Coding Standards

• Follow existing module layout and naming style.
• Keep functions small and purpose-focused.
• Prefer explicit error handling with clear console feedback.
• Avoid unrelated refactors in the same PR.

Testing Expectations

• Verify startup/login flow.
• Validate Tor-dependent commands still behave correctly.
• Confirm command syntax checks and error messages.
• Ensure new output files are written to expected data/ paths.

Commit Guidelines

• Use clear, imperative commit messages.
• Example:
  • docs: add usage and working guides
  • fix: handle invalid proxy url in changeproxy

Pull Request Checklist

• Code builds/runs locally
• Relevant commands tested
• Docs updated (README.md and related files)
• No secrets added to tracked files

Security and Legal

Do not submit code or examples that facilitate illegal activity. Contributions must align with responsible research and lawful use.