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
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 - OverviewStart 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 SolutionThe 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 PlanAt 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").
ExamplesTo help you get a feel for the sort of scope we are looking for, here are a few design document examples: