mirror of
https://github.com/GothenburgBitFactory/taskwarrior.git
synced 2025-07-07 20:06:36 +02:00
Documentation
- Updated developer documentation for 2.4.0.
This commit is contained in:
parent
1ac7dc0d5d
commit
560f41a930
2 changed files with 106 additions and 109 deletions
35
DEVELOPER
35
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
|
||||
Ask us about running a Flod satellite, we're always looking for exotic
|
||||
platforms to test on.
|
||||
page for an example: http://central.tasktools.org. 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.
|
||||
- Encouragement. Tell us what works for you, and what doesn't. Tell us about
|
||||
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.
|
||||
- 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?
|
||||
- Need unit tests for each bug in the issue list that is marked with the
|
||||
'needsTest' label.
|
||||
|
||||
* 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-04-13 Added answers.tasktools.org, corrected URLs.
|
||||
2014-05-11 Added build info.
|
||||
2014-05-31 Updated unit tests section.
|
||||
2014-07-04 Updated for 2.4.0
|
||||
|
|
38
EXPOSITION
38
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
|
||||
command determines whether subsequent arguments are interpreted as part of a
|
||||
filter or set of modifications.
|
||||
is to make multiple passes over the command line. For example, the command
|
||||
determines whether subsequent arguments are interpreted as part of a filter or
|
||||
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
|
||||
a set by the A3 (Args) object according to whether the command found is a
|
||||
read or write command.
|
||||
the complete command line. These arguments are extracted from the parse tree
|
||||
according to whether the command found is a 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,
|
||||
such that the result set contains only tasks for which the expression
|
||||
evaluates to Boolean true.
|
||||
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 evaluates
|
||||
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
|
||||
mostly written in Perl, and utilize the Test::More module to generate TAP
|
||||
output. Some tests are written in C++ and also generate TAP.
|
||||
regression and feature tests. The test are mostly written in Perl, and utilize
|
||||
the Test::More module to generate TAP output. This is changing though, and the
|
||||
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
|
||||
many platforms. Code changes are automatically detected, propagated, built and
|
||||
Taskwarrior uses flod software to automate continuous integration across many
|
||||
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.
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue