taskwarrior/DEVELOPER

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.
  While this is biased towards developers, anyone can contribute, and everyone
  is encouraged to do so.  Here are many ways to contribute that may not be
  immediately obvious to you:

  - 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.

  - Join us in the #taskwarrior IRC channel on freenode.net.  Some great ideas,
    suggestions, testing and discussions have taken place there.  It is also the
    quickest way to get help, or confirm a bug.

  - 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
    best way.  Perhaps you can help improve it.  Contact us - documentation is
    a separate effort from the codebase, and includes all web sites.

  - Take a look at the bug database, and help triage the bug list.  This is a
    review process that involves confirming bugs, providing additional data,
    information or analysis.  Bug triage is very useful and much needed.

  - 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.

  - 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.

  - 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
    will most likely be rejected.  The reason for this is that there are many
    efforts under way, in various code branches.  There is a very good chance
    that the feature you add is either already in progress, or being done in a
    way that is more fitting when considering other work in progress.  So if
    you want to add a feature, please don't.  Start by talking to us, and find
    out what is currently under way or planned.  You might find that we've
    already rejected such a feature for some very good reasons.  So please
    check first, so we don't duplicate effort or waste anyone's time.

  - 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
    Ask us about running a Flod satellite, we're always looking for exotic
    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
    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.

  Following are specific areas that could use some attention.

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.

  - Shadow file support in core.  It will migrate to become an external script.

  - Priorities in core.  This will be migrated to become a UDA as soon as we
    have the right support in place for custom sorting.

New Code Needs
  This is code that needs to be written, usually down at the C++ function/method
  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.  Find
    it, 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.
  - Need an external implementation equivalent to, or better than the 'shadow
    file' feature.  Simply because shadow file capability *can* be implemented
    outside the core code, we want to make it be that way.
  - Take a look at:

      http://taskwarrior.org/versions/show/42

    This 'extension' release is a collection of all the requested features that
    lie outside of the core product, and will be implemented as external scripts
    by anyone who wishes to participate.

Documentation Needed
  Documentation takes many forms, and we are trying to combine all documentation
  into one repository, to facilitate sharing and centralize review.  This
  includeѕ:

  - Man pages
  - Reference PDF
  - Wiki replacement
  - Tutorials
  - Cookbook

  This is all in the new git://tasktools.git/docs.git repository, where all the
  documents are sourced as markdown.  We welcome everyone with writing skills to
  help us improve this critical resource.

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
     git checkout 2.4.0
     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:

    cd 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 the file containing them 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, although with broken tests,
    who knows?

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

  Note that all new unit tests should follow the test/template.t standard.

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.

Current Codebase Condition

  'master' branch:
    - 2.3.0 Current release, locked.

  '2.3.0' branch:
    - Current release.  Locked.

  '2.3.1' branch:
    - For emergency releases.  Hopefully we won't need this.

  '2.4.0' branch:
    - Current development branch with new command line parser, expressions

---

2012-05-12 Added general statement about how to contribute.
2013-09-09 Updated branch info.
2014-01-19 Updated for 2.4.0.