How torproject/torspec works
Project type and purpose
• This repository is not an executable application but a “specification library” for Tor protocols. It holds text‐based protocol definitions, design proposals, and related documentation that guide implementers on how to build compatible Tor software without reading its source code.
File structure
• Top‐level files are grouped by protocol domain:
• General interest (tor‐spec.txt, cert‐spec.txt, dir‐spec.txt, etc.)
• Client operations (address‐spec.txt, path‐spec.txt, socks‐extensions.txt, etc.)
• Onion services (rend‐spec-v2.txt, rend‐spec-v3.txt)
• Censorship resistance (bridgedb‐spec.txt, pt‐spec.txt, gettor‐spec.txt)
• Directory authorities (bandwidth‐file‐spec.txt, srv-spec.txt)
• Controller protocol (control‐spec.txt)
• Miscellaneous and historical (dir-list-spec.txt, attic/)
• The proposals/ directory contains change proposals in numerical order and supporting scripts (reindex.py), plus a CI config (.gitlab-ci.yml) to validate or index them.
• .gitignore and versioning under GitLab imply a continuous integration workflow that checks syntax, links, or indexes.
README for additional insights
• It defines the purpose of each spec file and groups them by topic.
• It points to the proposal workflow (001-process.txt) and the role of proposals in evolving the main specs.
a. Main components:
• Spec Modules Group: each category (General, Client, Onion, Censorship, Authorities, Controller, Misc).
• Proposals Engine: the repository of design proposals feeding into spec evolution.
• CI Pipeline: linting, indexing, link‐checking, documentation build jobs.
• Consumers/Implementers: external Tor implementations (client, relay, controller libraries) that consume these specs.
• Version Control System (GitLab): source of truth and workflow enforcer.
b. Relationships and interactions:
c. Architectural patterns and design principles:
• Modular documentation: specs are decoupled by topic.
• Evolution-through-proposals: a formal change‐management workflow.
• Continuous validation: automated CI ensures spec integrity.
• Clear separation: stable specs vs. evolving proposals.
d. Key technologies and frameworks:
• Plain text / Markdown for specs.
• Python script (reindex.py) for indexing proposals.
• GitLab CI for pipeline orchestration.
• Version control (Git) for collaboration and branching.
Detailed capture of essential elements
• Proposal‐to‐spec transformation.
• Versioning: tags/branches in GitLab.
• Historical/archived docs (attic/) as deprecated.
• How a change in a proposal triggers CI checks, then merges into a stable spec.