Design Documents

Design Documents

This page is the entry point for Apache Traffic Server design work: proposals under discussion, designs that have been accepted, and where each of them lives.

Where a Design Document Lives

ATS keeps design documentation in two places, and the split matters:

Stage	Home	Why
Proposed / in flight	This wiki	Changes daily during discussion, is not tied to a release, and anyone can edit it without a PR round trip
Accepted / implemented	doc/developer-guide/design-documents/ in the repo	Versioned with the code it describes, reviewed via PR, published to the official docs

The rule of thumb: if it describes what ATS does today, it belongs in the repo. If it describes what ATS might do next, it belongs here. Once a design is accepted and the code lands, promote the document into doc/developer-guide/design-documents/ and replace the wiki page with a link.

In-Flight Designs

Proposals currently under discussion. Add a row when you start a design, and remove it when the design is either promoted to the repo docs or abandoned.

Design	Author	Status	Discussion
(none currently listed)

Status values: Draft (being written) · RFC (posted to dev@ for feedback) · Accepted (consensus reached, implementation underway) · Deferred · Withdrawn

Accepted Designs

Published in the official developer guide:

• Design Documents index

Related architecture and design material that also lives in the developer guide:

• Cache Architecture
• Core Architecture
• Logging Architecture
• Threads and Events
• Client Session Architecture

See also Architecture Overview for a shorter orientation to the codebase.

Proposing a Design

A design document is worth writing when a change is large enough that reviewers would rather argue about the approach than about the diff: new configuration surface, a new protocol or subsystem, a change to the plugin API, or anything that affects on-disk or on-wire compatibility. Small, self-contained changes do not need one — just open a PR.

1. Write the draft. Create a wiki page named Design: <Short Title> and add a row to the In-Flight Designs table above. Cover the problem, the proposed approach, alternatives you rejected and why, compatibility impact, and how it will be tested.
2. Post to dev@. Send a summary and a link to dev@trafficserver.apache.org and set the status to RFC. Design decisions are made on the mailing list, not on the wiki — the wiki holds the document, the list holds the discussion.
3. Iterate. Update the page as feedback comes in. Record significant objections and how they were resolved, so the reasoning survives after the thread scrolls away.
4. Implement. Once there is consensus, mark the design Accepted and open PRs referencing it.
5. Promote. When the implementation lands, move the document into doc/developer-guide/design-documents/ as a .rst file, then replace the wiki page with a pointer to the published version.

Writing a Good Design Document

• Lead with the problem, not the solution. Reviewers who disagree about the problem will never agree about the design.
• Record the alternatives you rejected. This is the part future readers need most, and the part authors most often skip.
• Be explicit about compatibility — configuration, plugin API, cache format, and on-wire behavior. These are what make a change hard to reverse.
• Say how it will be tested. See Testing.
• Keep the status current. A stale "Draft" that was actually abandoned two years ago is worse than no entry at all.

See Also

• Architecture Overview — How the pieces fit together today
• Contributing — Getting the resulting code merged
• Testing — Testing expectations for a new subsystem
• Developer's Guide — Full developer documentation