GothenburgBitFactory/taskwarrior
1
0
Fork 0
mirror of https://github.com/GothenburgBitFactory/taskwarrior.git synced 2025-06-26 10:54:26 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Documentation

Browse source 
- Updated developer docs, in preparation for beta.
This commit is contained in:
Paul Beckingham 2014-09-07 21:28:34 -04:00
parent e15907f3f1
commit 01f2db4b48
3 changed files with 64 additions and 67 deletions
Download patch file Download diff file Expand all files Collapse all files

88
DEVELOPER
View file

@ -1,9 +1,9 @@
How to Build
How to Build Taskwarrior
Obtain and build code:
$ git clone https://git.tasktools.org/scm/tm/task.git task.git
$ cd task.git
$ git checkout 2.4.0 # Dev branch
$ git checkout 2.4.0 # Latest dev branch
$ cmake -DCMAKE_BUILD_TYPE=debug . # debug or release. Default: neither.
$ make VERBOSE=1 # Shows details
@ -11,13 +11,16 @@ How to Build
$ cd tests
$ make VERBOSE=1 # Shows details
$ ./run_all # Runs all tests silently > all.log
# Install vramsteg for blinkenlights
$ ./problems # Find errors in all.log
# Install 'vramsteg' for blinkenlights
$ ./problems # Enumerate test failures 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.
If you send us a patch, make sure that patch is made against git HEAD. We
cannot apply patches made against the tarball source.
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.
@ -29,7 +32,7 @@ General Statement
always ongoing discussions about new features and changes to existing
features.
- Join us in the #taskwarrior IRC channel on freenode.net. Some great ideas,
- Join us in the #taskwarrior IRC channel on freenode.net. Many great ideas,
suggestions, testing and discussions have taken place there. It is also
the quickest way to get help, or confirm a bug.
@ -40,21 +43,27 @@ General Statement
- 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.
a separate effort from the codebase, and includes all web sites, and all
are available using git.
- 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.
information or analysis. Bug triage is very useful and much needed. You
could check to see that an old bug is still relevant - sometimes they are
not.
- Review the source code, and point out inefficiencies, problems, unreadable
functions, bugs and assumptions.
- 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 starting.
dependencies. We recommend talking to us before starting. Seriously.
- 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.
Plus, broken tests are a great motivator for us to fix the causal defect.
You'll need Python skills, as we are migrating from Perl to Python for our
test suite.
@ -83,7 +92,7 @@ General Statement
missing from the software, but gives us insights into how you use it.
Plus, you might get your feature implemented.
Following are specific areas that could use some attention.
Next are some specific areas that need attention.
Deprecated Code
This is code that is going to be phased out soon, and therefore is not worth
@ -94,26 +103,20 @@ Deprecated Code
- Priorities in core. This will be migrated to become a UDA as soon as we
have the right support in place for custom sorting.
- Nag feature.
- Attribute modifiers.
New Code Needs
This is code that needs to be written, usually down at the C++ function/method
level.
This is code that needs to be written.
- 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.
- Need export_viz.* 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.* 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.
linear performance curve, implying a slowdown due to fragmentation, but who
know? Find it, fix it.
- 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
@ -147,31 +150,7 @@ Unit Tests Needed
The tests are mainly written in Perl, and all use TAP. We want them all to be
eventually replaced by Python, so we are now only accepting new tests that use
the Python-based approach you can see in some of the existing tests. Here is
how to get the code and run the test suite:
git clone https://git.tasktools.org/scm/tm/task.git
cd task.git
git checkout 2.4.0
cmake -DCMAKE_BUILD_TYPE=debug .
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:
https://git.tasktools.org/scm/ut/vramsteg.git
the Python-based approach you can see in some of the existing tests.
Tests needed:
@ -188,8 +167,8 @@ Unit Tests Needed
- 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.
Note that running the unit tests currently requires the Perl JSON module to
be installed.
Note that all new unit tests should follow the test/template.t standard.
@ -207,10 +186,11 @@ Current Codebase Condition
- 2.3.0 Current release, locked.
'2.3.1' branch:
- Bug fix branch. To be released soon.
- Bug fix branch. Probably will not be released.
'2.4.0' branch:
- Current development branch with new command line parser, expressions
- Current development branch with new command line parser, expressions,
and heading for beta soon.
---

28
EXPOSITION
View file

@ -24,10 +24,14 @@ Command Line Parsing
determines whether subsequent arguments are interpreted as part of a filter or
set of modifications.
The Parser object is fed command line arguments, then through a succession of
calls builds and annotates a parse tree. To help with this, the Lexer is
used to break up strings into tokens.
Dispatch
Dispatch is simple: once the command line is parsed, the command is used to
look up a command object, then call its execute method.
look up a command object, then a call is made to the Command::execute method.
Context stores an associative map of command object pointers indexed by a
string. This means the 'done' string is an index to the CmdDone object that
@ -37,20 +41,22 @@ Dispatch
Command Objects
Every task command is implemented by a command object. The command object
provides metadata, usage and one-line help in addition to the ::execute method
that implements the command.
that implements the command. The Command base class implements common
functionality.
Column Objects
There is a 1:1 correspondence between attributes stored in the data files and
the columns that may be reported. These are represented by column objects,
which are responsible for validating input, measuring space needed according
to various formats, and for rendering data for reports.
to various formats, and for rendering data for reports. There is a
ColDescription object that inherits from a Column base class.
TDB2
The TDB2 object is a layered, transactioned I/O manager. Its purpose is to
isolate code from file I/O, locking, synching, and parsing details. It is
also responsible for minimizing reads, writes and parsing of data files.
isolate code from file I/O, locking and parsing details. It is also
responsible for minimizing reads, writes and parsing of data files.
All input is assumed to be UTF8. All stored data is UTF8.
@ -104,6 +110,12 @@ Filter
to Boolean true.
Eval & Variant
The Eval class evaluates expressions, provided in string form, using the
Variant class to represent data elements. Variant implements all operators
for all Variant types.
Sorting
Sorting is performed on a set of tasks. More specifically, the list that is
sorted is a set of numeric indexes to tasks that are stored in a separate
@ -147,14 +159,14 @@ Test Suite
suite is slowly migrating to Python. Some tests are written in C++ and all
tets generate TAP output.
There are currently about 9,000 unit tests, that take a minute or two to run
There are currently about 8,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
tested on a variety of participating platforms. Grid testing results are here:
http://central.tasktools.org/task-2.4.0.html
http://central.tasktools.org/
When making code changes, it is important that the test suite be run to verify
that functionality was not broken.
@ -174,7 +186,7 @@ Debugging
Patches
Patches are encouraged and welcomed. Either attach them to the appropriate
Redmine issue, or send them to support@taskwarrior.org. A good patch:
Jira issue, or send them to support@taskwarrior.org. A good patch:
- Maintains the MIT license, and does not contain code lifted from other
sources.

15
README.md
View file

@ -1,19 +1,24 @@
# Disclaimer during ongoing development
We want to discourage you from using the development version of Taskwarrior.
The development branch is a work in progress and may not pass all quality tests,
therefore it may harm your data. While we welcome bug reports from the
development branch, we do not guarantee proper or timely fixes.
therefore it may harm your data. We do not guarantee proper or even adequate
functionality, performance or timely fixes.
We welcome bug reports from beta- and release-level software, but generally not
development versions. If you are undaunted by this, please:
- Make proper backups.
- Broken functionality may arise from ongoing development work.
- Expect broken and missing functionality.
- Be aware that using the development branch involves risks.
---
Thank you for taking a look at taskwarrior!
Thank you for taking a look at Taskwarrior!
Taskwarrior is a GTD, todo list, task management, command line utility with a
multitude of features. It is a portable, well supported, very active Open
multitude of features. It is a portable, well supported and very active Open
Source project. Taskwarrior has binary distributions, online documentation,
demonstration movies, and you'll find all the details at: