Documentation

- Updated developer documentation for 2.4.0.

DEVELOPER

@@ -14,6 +14,10 @@ How to Build
                                          # Install vramsteg for blinkenlights
     $ ./problems                         # Find errors in all.log
 
+  Note that any development should be performed using a git clone, and the
+  current development branch. The source tarballs do not reflect HEAD, and do
+  not contain the test suite.
+
 General Statement
   This file is intended to convey the current efforts, priorities and needs of
   the codebase. It is for anyone looking for a way to start contributing.
@@ -23,7 +27,7 @@ General Statement
 
   - Use Taskwarrior, become familiar with it, and make suggestions. There are
     always ongoing discussions about new features and changes to existing
-    features.  Join us in the forums.
+    features.
 
   - Join us in the #taskwarrior IRC channel on freenode.net. Some great ideas,
     suggestions, testing and discussions have taken place there. It is also
@@ -31,7 +35,7 @@ General Statement
 
   - Join https://answers.tasktools.org and help us by asking, answering and
     voting on questions and answers, directly helping those who ask, and
-    indirectly helping those who search for existing answers.
+    helping future users who search for existing answers.
 
   - Review documentation: there are man pages, online articles, tutorials and
     so on, and these may contain errors, or they may not convey ideas in the
@@ -45,12 +49,14 @@ General Statement
   - Fix a bug. For this you'll need C++ and Git skills, but this is one of
     the largest ways you can contribute. We welcome all bug fixes, provided
     the work is done well and doesn't create other problems or introduce new
-    dependencies.  We recommend talking to us before embarking on this quest.
+    dependencies. We recommend talking to us before starting.
 
   - Add unit tests. Unit tests are possibly the most useful contributions of
     all, because they not only improve the quality of the code, but prevent
     future regressions, therefore maintaining quality of subsequent releases.
     Plus, broken tests are a great motivator for us to fix the causal bug.
+    You'll need Python skills, as we are migrating from Perl to Python for our
+    test suite.
 
   - Add a feature. Well, let's be very clear about this: adding a feature is
     not usually well-received, and if you add a feature and send a patch, it
@@ -65,14 +71,13 @@ General Statement
 
   - Donate some server time to the testing effort, by participating in the
     continuous integration of all changes, with our Flod software. See this
-    page for an example:  http://tasktools.org/tinderbox
+    page for an example:  http://central.tasktools.org. Ask us about running a
-    Ask us about running a Flod satellite, we're always looking for exotic
+    Flod satellite, we're always looking for exotic platforms to test on.
-    platforms to test on.
 
   - Spread the word. Help others become more effective at managing tasks.
 
-  - Encouragement.  Tell us what works for you, and what doesn't.  It's all
+  - Encouragement. Tell us what works for you, and what doesn't. Tell us about
-    good.
+    your methodology for managing tasks. It's all good.
 
   - Request a feature. This not only tells us that you think something is
     missing from the software, but gives us insights into how you use it.
@@ -180,11 +185,8 @@ Unit Tests Needed
     basic.t.
   - Test propagation of modifications to recurring tasks.
   - Test regex support.
-  - Need unit tests for each bug in the issue list, if suitable.
+  - Need unit tests for each bug in the issue list that is marked with the
-  - We have bugs in the unit tests that only manifest on days such as December
+    'needsTest' label.
-    31st.  Clearly there is some bad date math going on, most likely in the
-    tests themselves, rather than in Taskwarrior, although with broken tests,
-    who knows?
 
   * Note that running the unit tests requires the Perl JSON module to be
     installed.
@@ -196,8 +198,6 @@ Work in Progress
   Things that are currently in flux, which is another way of saying leave it
   alone while it is being worked on.
 
-  - Command line parser (A3).
-  - Expression evaluation (E9).
   - All columns/Col*::validate methods.
   - New columns/Col*::modify methods.
 
@@ -214,7 +214,4 @@ Current Codebase Condition
 
 ---
 
-2014-01-19 Updated for 2.4.0.
+2014-07-04 Updated for 2.4.0
-2014-04-13 Added answers.tasktools.org, corrected URLs.
-2014-05-11 Added build info.
-2014-05-31 Updated unit tests section.

EXPOSITION

@@ -20,9 +20,9 @@ Startup
 
 Command Line Parsing
   Command line parsing is difficult because of all the ambiguity. The solution
-  is to make several passes over the command line.  For example, the task
+  is to make multiple passes over the command line. For example, the command
-  command determines whether subsequent arguments are interpreted as part of a
+  determines whether subsequent arguments are interpreted as part of a filter or
-  filter or set of modifications.
+  set of modifications.
 
 
 Dispatch
@@ -94,15 +94,14 @@ Files
 
 Filter
   A filter is simply a set of command line arguments, but is only a subset of
-  the complete command line.  These arguments (Arg objects) are grouped into
+  the complete command line. These arguments are extracted from the parse tree
-  a set by the A3 (Args) object according to whether the command found is a
+  according to whether the command found is a read or write command.
-  read or write command.
 
-  There is a Command::filter method for applying a filter to a set of tasks,
+  There is a Filter::subset method for applying a filter to a set of tasks,
   yielding a result set. It does this by creating an expression from the
-  filter using the E9 object, then evaluating the expression for each task,
+  parse tree using the Eval object, then evaluating the expression for each task,
-  such that the result set contains only tasks for which the expression
+  such that the result set contains only tasks for which the expression evaluates
-  evaluates to Boolean true.
+  to Boolean true.
 
 
 Sorting
@@ -143,18 +142,19 @@ Test Suite
   are sound.
 
   It is intended that the test suite continues growing, mostly adding more
-  regression tests (bug.*.t) and more feature tests (feature.*.t).  The test are
+  regression and feature tests. The test are mostly written in Perl, and utilize
-  mostly written in Perl, and utilize the Test::More module to generate TAP
+  the Test::More module to generate TAP output. This is changing though, and the
-  output.  Some tests are written in C++ and also generate TAP.
+  suite is slowly migrating to Python. Some tests are written in C++ and all
+  tets generate TAP output.
 
-  There are currently over 5,000 unit tests, that take a minute or two to run
+  There are currently about 9,000 unit tests, that take a minute or two to run
   in total.
 
-  Taskwarrior uses flod software to automate continuous integration across
+  Taskwarrior uses flod software to automate continuous integration across many
-  many platforms. Code changes are automatically detected, propagated, built and
+  platforms. Code changes are automatically detected, propagated, built and
   tested on a variety of participating platforms. Grid testing results are here:
 
-    http://tasktools.org/tinderbox/taskwarrior-2.4.0.html
+    http://central.tasktools.org/task-2.4.0.html
 
   When making code changes, it is important that the test suite be run to verify
   that functionality was not broken.
@@ -168,7 +168,7 @@ Debugging
       http://tasktools.org/performance).
     - Data load times.
     - Terminal size, color capabilities.
-    - Command line parsing steps, shown in colorful diagrams.
+    - Colorful, confusing, command line parse tree.
     - TDB2 layer and I/O information.
 
 
@@ -181,7 +181,7 @@ Patches
     - Precisely addresses one issue only.
     - Doesn't break unit tests.
     - Doesn't introduce dependencies.
-    - Is accompanied by unit tests, where appropriate.
+    - Is accompanied by unit tests, where appropriate, written in Python.
     - Is accompanied by documentation changes, where appropriate.
     - Conforms to the prevailing coding standards - in other words, it should
       fit right in with the existing code.