mirror of
https://github.com/GothenburgBitFactory/taskwarrior.git
synced 2025-06-26 10:54:26 +02:00
192 lines
8.8 KiB
Text
192 lines
8.8 KiB
Text
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 # Latest dev branch
|
|
$ cmake -DCMAKE_BUILD_TYPE=debug . # debug or release. Default: neither.
|
|
$ make VERBOSE=1 # Shows details
|
|
|
|
Running Test Suite:
|
|
$ cd tests
|
|
$ make VERBOSE=1 # Shows details
|
|
$ ./run_all # Runs all tests silently > 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.
|
|
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 #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.
|
|
|
|
- Join https://answers.tasktools.org and help us by asking, answering and
|
|
voting on questions and answers, directly helping those who ask, and
|
|
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
|
|
best way. Perhaps you can help improve it. Contact us - documentation is
|
|
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. 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. 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 defect.
|
|
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
|
|
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://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. 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.
|
|
Plus, you might get your feature implemented.
|
|
|
|
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
|
|
fixing or documenting. Don't waste your time.
|
|
|
|
- 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.
|
|
|
|
- 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, 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
|
|
properly handle recurring tasks.
|
|
- Take a look at:
|
|
|
|
https://bug.tasktools.org/browse/EX
|
|
|
|
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.
|
|
|
|
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. 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.
|
|
|
|
Tests needed:
|
|
|
|
- Take a look at the bug database (https://bug.tasktools.org) and notice that
|
|
many issues, open and closed, have the "needsTest" label. These are things
|
|
that we would like to see in the test suite, as regression tests.
|
|
- 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.
|
|
- Test propagation of modifications to recurring tasks.
|
|
- Test regex support.
|
|
- Need unit tests for each bug in the issue list that is marked with the
|
|
'needsTest' label.
|
|
|
|
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.
|
|
|
|
Work in Progress
|
|
|
|
Things that are currently in flux, which is another way of saying leave it
|
|
alone while it is being worked on.
|
|
|
|
- All columns/Col*::validate methods.
|
|
- New columns/Col*::modify methods.
|
|
|
|
Current Codebase Condition
|
|
|
|
'master' branch:
|
|
- 2.3.0 Current release, locked.
|
|
|
|
'2.4.0' branch:
|
|
- Current development branch with new command line parser, expressions,
|
|
and heading for beta soon.
|
|
|
|
---
|
|
|
|
2014-10-12 Updated for 2.4.0
|