Andy Lester

NAME

hwd -- The How We Doin'? project tracking tool

SYNOPSIS

hwd [options] schedule-file(s)

Options:

        --nextid    Display the next highest task ID
        --todo      Displays tasks left to do, started or not.
        --started   Displays tasks that have been started
        --started=person
                    Displays tasks started by person
        --tasks     Displays tasks sorted by person
        --tasks[=person]
                    Displays tasks for a given user
        --burndown  Display a burn-down table

        --wrap=n    Wrap output at n columns, or 0 for no wrapping.
                    Default is 72, or terminal width if available.
        --csv       Output in CSV format
        --nonotes   Omit the notes from the output
        --strict    Die on problems in the input file (default)
        --nostrict  Print output even if there are non-fatal errors

    -h, --help      Display this help
    -H, --man       Longer manpage for prove
    -V, --version   Display version info

COMMAND LINE OPTIONS

--todo

Limit the dump of tasks to only those that are left to do, whether or not they've been started.

--started[=who]

Shows what tasks have been started by the person specified, or by everyone if no one one is specified.

    Ape is working on...
      104 - Add FK constraints between FOOHEAD and BARDETAIL (2/2)

    Chimp is working on...
      107 - Refactor (1/1)

--tasks[=person]

Shows the list of tasks and their status sorted by user. If a person is specified, only the tasks for that person will be shown.

--nextid

Shows the next ID available.

--burndown

Print a "burn down" graph:

    YYYY/MM/DD      Total   Todo
    2005/07/15      100     98
    2005/07/17      100     77
    2005/07/18      100     75
    2005/07/19      100     70

That is, how fast is the amount of work left "burning down" to zero?

--strict, --nostrict

By default, --strict is on and hwd will not print output if there are errors in the input. You can use the --nostrict for when you're getting your first schedule pulled together and don't mind the errors and the inaccuracies they cause, in the name of seeing some output.

-V, --version

Display version info.

HWD FILE FORMAT

The HWD file format is intentionally very simple. It's designed to be usable in plain ol' text editors, and merge easily in a version control system like Subversion.

The order of lines in the file are significant, except for work lines that correspond to a numbered task.

TASKS

The core of an .hwd file is the task line. Each task line corresponds to one task. Here are some sample task lines:

    -Report printing
    --Data entry screen (4h, #101)
    --Data entry validation (6h, #102)
        Needs to handle Canadian postcodes, too.
    --Data marshalling
    ---Design temp tables (2h, #67, added 2006-01-05)
    ---SQL queries (4h, #103)
    --Report generation
    ---Install Report-o-gram (2h, #105, deleted 2006-02-08)
        Not needed for this project.  We'll work with what we have.
    ---Write report code (2h, #106)

The number of dashes before each line indicate the depth in the work outline. The text up to the parentheses is the name/description of the task. Lines beginning with whitespace are notes (see below).

The parenthetical block is control information for the task, and may include any of the following, separated by commas, in any order:

  • Task number

    The task number is an optional, unique, arbitrary, numeric key for the task. If you're not doing task tracking, you don't need one. The task number must match /^#\d+$/.

  • Time estimate

    Estimated amount of actual work to be done on the task. Rollup tasks, or tasks with subtasks, may not have time estimates on them. Times must match /^(\d+\.)?\d+h$/ for hours, or /^\d+m$ for minutes.

  • Date added

    Tells the date the task was added to the schedule

  • Date deleted

    Tells the date the task was deleted from the schedule. Note that it appears in the file, but if you just delete the line from the file, you won't have that history to tell that your amount of work went down.

NOTES AND COMMENTS

Any line that starts with whitespace is seen as a note for the task immediately preceding it.

Any line that begins with a # is a comment in the file, and is ignored during processing.

TRACKING WORK

If you want to use hwd as just an outliner/scheduler, that's fine. However, you can then put your work entries into the .hwd file and have hwd tell you how you're doing on the project.

Work is recorded with work lines that follow this format:

    Who     Date    Task#   Time X?

All fields are separated by whitespace, and the Who column cannot contain spaces. The optional X tells whether the task was completed or not.

Here are some examples.

    --Do some stuff (#105)
    --Do some other stuff (#253)
    Arlo    3/09    105     3h
    Arlo    3/09    253     15m X

Arlo worked on March 9th on task 105 for 3 hours, and then on task 253 for 15 minutes, and completed it. At this point, task 105 is open and 253 is closed.

Later, we find these work entries.

    Arlo    3/10    105     2 X
    Arlo    3/10    253     5

Arlo finished up 105, but found bugs in task 253 and went back to work on it. Now, task 105 is closed, and 253 has been re-opened because more work was done on it without having been completed. Note that without specifying "h" for hours or "m" for minutes, hwd assumes hours.

It's not necessary to have numbered tasks to use the work tracking. If you don't want to hassle with numbering, you can use the magic task number of ^ (caret) to apply the work to the most recent task in the file. For example, our previous examples could have been written as

    --Do some stuff (#105)
    Arlo    3/09    ^       3
    Arlo    3/10    ^       2 X
    --Do some other stuff (#253)
    Arlo    3/09    ^       .25h X
    Arlo    3/10    ^       5h

Note that for unnumbered tasks, the relative order of the lines is important so that the work is applied to the appropriate tasks. For numbered tasks, tasks and work can appear in any order. Also, you can combine numbered and unnumbered, so that you can have:

    --Do some stuff (#105)
    --Do some other stuff (#253)
    Arlo    3/09    105     2 X
    Arlo    3/10    ^       5
    Arlo    3/10    105     15m X
    Arlo    3/09    ^       3

TODO

  • Better documentation

  • Samples so that prospective users can see what it will do.

  • Tutorial showing different commands and output

  • Add support for HWDFILE environment variable so those of us who are only ever using one file don't have to keep retyping the name all the time.

  • Make sure a rollup task has no hours, and that any task with no hours has tasks below it.

  • Add support for changing estimates on a task

  • Open tasks are doubling up if two people have it open.

  • Show task history

  • Show tasks that are too big.

  • Show tasks that have gone over

  • Weekly burndown

    The --burndown flag gives totals as they happen. I want them to give a Monday-morning total since I like to plot weekly, not daily.

BUGS

Please use the CPAN bug ticketing system at http://rt.cpan.org/. You can also mail bugs, fixes and enhancements to <bug-app-hwd at rt.cpan.org>.

AUTHORS

Andy Lester <andy at petdance.com>

COPYRIGHT

Copyright 2006 by Andy Lester <andy at petdance.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html.