taskwarrior/DEVELOPER

This file is intended to convey the current efforts, priorities and needs of the
codebase.  It is for developers looking for a way to start contributing.


Deprecated Code
  This is code that is going to be phased out soon, and therefore is not worth
  fixing or documenting.  Don't waste your time.

  - There is no deprecated code at the moment.  I'm sure there will be soon.

New Code Needs
  This is code that needs to be written, usually down at the C++ function level.

  - Need export_viz.yy script.  Any language.  This would have value as an
    example, or template script serving as a starting-point for anyone who
    needed this format.
  - Need new export_xxx.yy scripts - the more the better.  Any language.
  - The JSON.{h,cpp} code is fast and efficient up to a point, but has a non-
    linear performance curve, implying a slowdown due to fragmentation.  Fix it.
  - Need a function that can optimize color codes.  For example, if a string
    contains this:
      <red>one two </red><red>three four</red>
    It can be shortened to:
      <red>one two three four</red>
    This is only possible if there is nothing between </red> and <red> and the
    colors match.
  - Need an external script that can locate and correct duplicate UUIDs in the
    data file, as found by 'task diag'.  This should check to see if there is
    a suitable UUID generator installed.  This should also be careful to
    properly handle recurring tasks.

Documentation Needed
  Various forms of documentation that are needed, or are in need of review or
  update.

  - Wiki/How-To: Date Handling
  - Wiki/How-To: Custom Reports, including performance considerations
  - Wiki/How-To: Aliases, particularly new enhanced aliases
  - Wiki/Features: All sections

Unit Tests Needed
  There are always more unit tests needed.  More specifically, better unit tests
  are always needed.  The convention is that there are four types of unit test:

  1. High level tests that exercise large features, or combinations of commands.
     For example, dependencies.t runs through a long list of commands that test
     dependencies, but do so by using 'add', 'modify', 'done' and 'delete'.
  2. Regression tests that ensure certain bugs are fixed and stay fixed.  These
     tests are named bug.NNN.t where NNN refers to the Redmine issue number.
     While it is not worth creating tests for small fixes like typos, it is for
     changes to the logic.
  3. Small feature tests.  When small features are added, we would like small,
     low-level feature tests named feature.NNN.t, where NNN is the Redmine
     issue number.
  4. Code tests.  These are tests written in C++ that exercise C++ objects, or
     function calls.  These are the lowest level tests.  It is important that
     these kind of tests be extensive and thorough, because the software depends
     on this code the most.

  The tests are mainly written in Perl, and all use TAP.  Here is how to get the
  code and run the test suite:
     git clone git://tasktools.org:task.git
     cd task.git
     cmake .
     make
     make test

  Alternately, you go to the test directory and run the following:

     cd task.git/test
     make
     make test

  Either way, a TAP file 'all.log' is written that contains all test results.
  once this file is created, you can see the failing tests using this script:

    task.git/test/problems

  If you make a habit of running the test suite, consider downloading the
  vramsteg utility to show a colorful progress bar, from:

    git://tasktools.org/vramsteg.git     

  Tests needed:

  - The basic.t unit tests are a misnomer, and should be either removed or
    renamed.  We have long talked of 'basic functionality' that includes add,
    delete, done, and list commands.  We need unit tests that prove that basic
    functionality is working, and it should be called basic.t.
  - None of the current unit tests remove the 'extensions' directory, and they
    all should.
  - Test propagation of modifications to recurring tasks.
  - Test regex support.
  - Need unit tests for each bug in the issue list, if suitable.
  - We have bugs in the unit tests that only manifest on days such as December
    31st.  Clearly there is some bad date math going on, most likely in the
    tests themselves, rather than in taskwarrior.

  * Note that running the unit tests require the Perl JSON module to be
    installed.

Work in Progress
  Things that are currently in flux, which is another way of saying leave it
  alone while it is being worked on.

  - None.

Current Codebase Condition

  'master' branch:
    - 2.0.0 release, current, locked.

  '2.0.1' branch:
    - All current development.

  '2.1.0' branch:
    - Future development effort.

---

2012-03-25 Corrected codebase condition details.
2012-03-03 Updated text, removed old history info.