HTCondor Design Documents
If your change is an enhancement (new feature) or large bug fix, you will need to author and attach a design document to the ticket page for architecture review and get it approved before code contributions will be accepted. It is typical for a design document to go through several revisions. Although they are generally pithy and to the point (2 or 3 pages is typical), the generation and review of a well thought-out design document can be a time-consuming undertaking. But we feel it is necessary to ensure the architectural integrity and correctness of the code base, and ultimately the time spent writing a design document is time well-spent.
Two to four pages is typical, but could be more or less depending on the situation.
As of July, 2013, new design documents should be Google Drive documents to ensure they are self-contained, have revision tracking, and reduce the risk of version skew. See GoogleDriveWisdom for details on usage.
Older design documents are .docx files (either Microsoft Word or
Open Office/Libre Office) to ensure they are self-contained and to leverage revision tracking as they are passed around for review and refinement.
Outline of a Design Document
A design document has three major sections; each is outlined below. While you can assume that the reader is familiar with pre-existing design and implementation of the code, this is not an email or wiki post - the document itself should be self-contained and able to "make sense" on its own. This is part of the reason we require a separate document outside of the ticket itself. A developer five years from now, who was not involved in a recent string of email discussions or lacks access to pages of ticket remarks, should be able to read the document on its own and gain insight and understanding.
Section One - Overview
Start out by providing information about the motivation - what is the problem, why is it
important to solve the problem, what is the general approach? What
insights led us to the problem, what new understanding is characterized
in how we will solve it? Try to identify the requirements of the new enhancement, and how were these requirements gathered/identified? If the problem is related to a specific usage scenario or environment, include as salient details about the motivating scenario/environment. Try to keep the implementation details to a bare
minimum when answering these questions. Instead, think about what the reader will have learned
after reading your overview about the problem itself and the tradeoffs
involved in finding a solution.
Section Two - Architecture of Proposed Solution
The body of the document will describe the general architecture of
the proposed solution : What components are involved? What is the
responsibility of each component? How will the components interact? What
will the final result look like to the end-user? It is good to talk
about some implementation details here, especially if it enables deeper
understanding by an informed reader (i.e. "communication will occur via
a daemonCore command socket" tells a lot to a reader familiar with this
class). Think about fault tolerance, verification, maintainability, ease
of use, ease of implementation, backwards-compatibility, code/component
re-use.
Section Three - Development Plan
At the end of the document should be a list of development
Milestones in chronological order. Each milestone should include a
best-guess effort estimate; resolution of each milestone should be on
the order of 1 to 10 days. If specialized knowledge is required and/or it is not clear that a specific individual(s) will perform the work, you
are encouraged to explicitly list that and/or give multiple effort
estimates (e.g. "3 days for someone familiar with DAGMan internals such
as Kent or Nathan, or 9 days for a different member of the HTCondor core
development team, or 20 days for someone unfamiliar with the code-base").
Examples
To help you get a feel for the sort of scope we are looking for, here are a few design document examples: