pintos-os.org Git - pintos-anon/blob - doc/doc.texi

   1 @node Project Documentation, Debugging Tools, Coding Standards, Top
   2 @appendix Project Documentation
   3
   4 When you submit your projects, you will be expected to also turn in
   5 three files documenting them: @file{README}, @file{DESIGNDOC} and
   6 @file{TESTCASE}.  These guidelines explain what we want to see in
   7 those files.
   8
   9 Your submission should have exactly one of each file, in the
  10 appropriate directory (e.g.@: for Assignment 1, place the files in the
  11 @file{threads} directory).  These files must be written in plain text
  12 format (not Microsoft Word, not PDF).  We recommend a text width of 65
  13 characters per line, with a hard limit of 80.
  14
  15 @menu
  16 * README::
  17 * DESIGNDOC     ::
  18 * TESTCASE      ::
  19 @end menu
  20
  21 @node README
  22 @section @file{README}
  23
  24 This is the easiest of the bunch.  It's the document we'll read while
  25 trying to get your assignment to run.  First, place all of your names
  26 and Leland IDs (usernames) at the top.  Next, you should also explain
  27 any quirks with your program, such as known show-stopper bugs, weird
  28 dependencies, and so on.
  29
  30 If you added extra credit features to your project, explain them
  31 concisely in the @file{README}.  Otherwise, we're likely to miss them.
  32
  33 @node DESIGNDOC
  34 @section @file{DESIGNDOC}
  35
  36 This file is our primary tool for assessing your design.  Therefore,
  37 you should be certain to explain your design in some decent amount of
  38 detail.  As a broad rule of thumb, we should be able to explain what
  39 basic data structures and algorithms you used to solve the problem
  40 after reading the @file{DESIGNDOC}, but without looking at the code.
  41
  42 The easiest way to present your @file{DESIGNDOC} is to break it down
  43 by parts of the project (e.g.@: for project 1, you can break the
  44 @file{DESIGNDOC} into four parts).  For each part, you should describe
  45 the functionality that needs to be added, the data structures and
  46 algorithms used to solve that problem from a high level, and the
  47 motivations for each decision/change you make to the code.  Your
  48 @file{DESIGNDOC} needs to explain and justify your design.  That is,
  49 we should be able to understand what you did, and why you chose to do
  50 it that way.  The ``why'' should be in concrete terms of greater speed,
  51 better space efficiency, cleaner code, or some other real measure of
  52 goodness.
  53
  54 Things you @emph{don't} need: an explanation of the pre-existing
  55 Pintos code, an explanation of the project spec, justification for the
  56 project (e.g.@: we don't need you to explain to us why filesystems are
  57 important to an operating system), a play-by-play of every change you
  58 made to the system, any other pontificating.  (You may laugh at some
  59 of the things listed above, but we've gotten all of them in the past.)
  60 The @file{DESIGNDOC} needs to discuss design decisions and trade-offs
  61 and the rationales behind them.  Any other things can be left out, to
  62 save your time and ours.
  63
  64 Finally, please keep your @file{DESIGNDOC} as short as you can,
  65 without sacrificing key design decisions.  You should be brief, yet
  66 complete.  We don't want to read novels.
  67
  68 @node TESTCASE
  69 @section @file{TESTCASE}
  70
  71 The @file{TESTCASE} file should contain all the information about how
  72 you tested your programs.  At minimum, this file should contain the
  73 output from all the tests that we've provided, with any explanations
  74 needed to reproduce the output (arguments to the program, turning
  75 features on the program on or off, and so on).
  76
  77 Additionally, you should detail all tests you write yourself.  You are
  78 expected to write tests for features which our tests don't cover, and
  79 to write some additional stress tests, since our tests will not
  80 necessarily be too strenuous.  If you feel that such tests are not
  81 required, you should explain why you feel so.  For each test that you
  82 write, explain how we can use them, and show some sample output from a
  83 run.
  84
  85 Specifically, here are some pointers for writing @file{TESTCASE} files
  86 which will make them more succinct and us more likely to understand the
  87 tests you write:
  88
  89 @itemize @bullet
  90 @item
  91 Show us that you tested each part of your assignment.
  92
  93 @item
  94 Clearly state in your @file{TESTCASE} file what each test is supposed
  95 to test.  You should be testing not only the common case, but testing
  96 corner cases.  Specify what criteria or issue is being tested.  For
  97 example, in testing @code{thread_join()} you would have specified that
  98 you test @code{thread_join()} when it is called multiple times on the
  99 same child thread.
 100
 101 @item
 102 Make your tests as succinct as possible.  Most students in the past
 103 have done a great job with the testing of @code{thread_join()},
 104 creating very succinct short tests.  We like that.
 105
 106 @item
 107 Your test cases should be placed in a subdirectory called
 108 @file{testcases} within the project directory.  So for project 1, they
 109 should be in @file{pintos/src/threads/testcases}.
 110
 111 @item
 112 Think about what may actually crash your code.
 113 @end itemize
 114
 115 Your @file{TESTCASE} file is also where you can show us the
 116 improvements that your code makes to the performance of the system.
 117 You should be able to show us ``before'' and ``after'' performance
 118 data, and explain how the data shows the improvement.  For example,
 119 for Problem 1-4, you should show us in the @file{TESTCASE} printouts
 120 from a workload for the non-Solaris scheduler and the Solaris
 121 scheduler and explain why the Solaris scheduler is better.
 122
 123 Finally, we cannot stress enough the importance of being brief and
 124 complete.
 125
 126 Keep in mind that the quality of your testing is worth 10% of your
 127 project grade.  The bulk of this will be determined from the
 128 @file{TESTCASE} file.