mirror of
https://github.com/GothenburgBitFactory/taskwarrior.git
synced 2025-06-26 10:54:26 +02:00
Import design docs (RFCs)
This commit is contained in:
Dustin J. Mitchell
Tomas Babej
parent
07493d5fa6
commit
8747cc9f94
15 changed files with 3259 additions and 0 deletions
|
|
@ -13,3 +13,22 @@ For all other documenation, see https://taskwarrior.org.
|
|||
* [Building Taskwarrior](./contrib/build)
|
||||
* [Coding Style](./contrib/coding_style)
|
||||
* [Branching Model](./contrib/branching)
|
||||
|
||||
## RFC's
|
||||
|
||||
This is where design documents (RFCs) are kept.
|
||||
|
||||
Although these documents are less formal than [IETF RFCs](https://www.ietf.org/rfc) they serve a similar purpose.
|
||||
These documents apply only to the Taskwarrior family of products, and are placed here to invite comment before designs finalize.
|
||||
|
||||
- [General Plans](./rfcs/plans)
|
||||
- [Rules System](./rfcs/rules)
|
||||
- [Full DOM Support ](./rfcs/dom)
|
||||
- [Work Week Support](./rfcs/workweek)
|
||||
- [Recurrence](./rfcs/recurrence)
|
||||
- [Taskwarrior JSON Format](./rfcs/task)
|
||||
- [CLI Updates ](./rfcs/cli)
|
||||
- [Taskserver Sync Protocol](./rfcs/protocol)
|
||||
- [Taskserver Message Format](./rfcs/request)
|
||||
- [Taskserver Sync Algorithm](./rfcs/sync)
|
||||
- [Taskserver Client](./rfcs/client)
|
||||
|
|
|
|||
24
docs/rfcs/_index.md
Normal file
24
docs/rfcs/_index.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
title: "Taskwarrior - What's next?"
|
||||
---
|
||||
|
||||
# Design
|
||||
|
||||
## Plans
|
||||
|
||||
- [Task warrior/Taskserver/Tasksh/Timewarrior Plans](/docs/design/plans)
|
||||
|
||||
## RFCs
|
||||
|
||||
|
||||
### Tasksh
|
||||
|
||||
- (No announced plans)
|
||||
|
||||
### Timewarrior
|
||||
|
||||
- (No announced plans)
|
||||
|
||||
### Upcoming
|
||||
|
||||
- Lazy Dates (Deferred Evaluation)
|
||||
162
docs/rfcs/cli.md
Normal file
162
docs/rfcs/cli.md
Normal file
|
|
@ -0,0 +1,162 @@
|
|||
---
|
||||
title: "Taskwarrior - Command Line Interface"
|
||||
---
|
||||
|
||||
## Work in Progress
|
||||
|
||||
This design document is a work in progress, and subject to change. Once
|
||||
finalized, the feature will be scheduled for an upcoming release.
|
||||
|
||||
|
||||
# CLI Syntax Update
|
||||
|
||||
The Taskwarrior command line syntax is being updated to allow more consistent
|
||||
and predictable results, while making room for new features.
|
||||
|
||||
Adding support for arbitrary expressions on the command line has become
|
||||
complicated because of the relaxed syntax of Taskwarrior. While the relaxed
|
||||
syntax allows for a very expressive command line, it also creates ambiguity for
|
||||
the parser, which needs to be reduced.
|
||||
|
||||
With some limited and careful changes it will be possible to have a clear and
|
||||
unambiguous command line syntax, which means a predictable and deterministic
|
||||
experience.
|
||||
|
||||
It should be stated that for straightforward and even current usage patterns,
|
||||
the command line will likely not change for you. Another goal is to not require
|
||||
changes to 3rd-party software, where possible. Only the more advanced and as-yet
|
||||
unintroduced features will require a more strict syntax. This is why now is an
|
||||
ideal time to tighten the requirements.
|
||||
|
||||
|
||||
## Argument Types
|
||||
|
||||
The argument types supported remain the same, adding some new constructs.
|
||||
|
||||
--------------------------------------- ---------------------------------------
|
||||
Config file override `rc:<file>`
|
||||
|
||||
Configuration override `rc:<name>:<value>` Literal value\
|
||||
`rc:<name>=<value>` Literal value\
|
||||
`rc:<name>:=<value>` Calculated value
|
||||
|
||||
Tag `+<tag>`\
|
||||
`-<tag>`\
|
||||
`'+tag one'` Multi-word tag
|
||||
|
||||
Attribute modifier `rc:<name>.<modifier>:<value>`\
|
||||
Modifier is one of:\
|
||||
`before`\
|
||||
`after`\
|
||||
`under`\
|
||||
`over`\
|
||||
`above`\
|
||||
`below`\
|
||||
`none`\
|
||||
`any`\
|
||||
`is`\
|
||||
`isnt`\
|
||||
`equals`\
|
||||
`not`\
|
||||
`contains`\
|
||||
`has`\
|
||||
`hasnt`\
|
||||
`left`\
|
||||
`right`\
|
||||
`startswith`\
|
||||
`endswith`\
|
||||
`word`\
|
||||
`noword`
|
||||
|
||||
Search pattern `/<pattern>/`
|
||||
|
||||
Substitution `/<from>/<to>/`\
|
||||
`/<from>/<to>/g`
|
||||
|
||||
Command `add`\
|
||||
`done`\
|
||||
`delete`\
|
||||
`list`\
|
||||
etc.
|
||||
|
||||
Separator `--`
|
||||
|
||||
ID Ranges `<id>[-<id>][,<id>[-<id>]...]`
|
||||
|
||||
UUID `<uuid>`
|
||||
|
||||
Everything Else `<word>`\
|
||||
`'<word> <word> ...'`
|
||||
--------------------------------------- ---------------------------------------
|
||||
|
||||
|
||||
## New Command Line Rules
|
||||
|
||||
Certain command line constructs will no longer be supported, and this is imposed
|
||||
by the new rules:
|
||||
|
||||
1. Each command line argument may contain only one instance of one argument
|
||||
type, unless that type is `<word>`.
|
||||
|
||||
task add project:Home +tag Repair the thing # Good
|
||||
task add project:Home +tag 'Repair the thing' # Good
|
||||
task add 'project:Home +tag Repair the thing' # Bad
|
||||
|
||||
Putting two arguments into one quoted arg makes that arg a `<word>`.
|
||||
|
||||
2. If an argument type contains spaces, it must either be quoted or escaped.
|
||||
|
||||
task add project:'Home & Garden' ... # Good
|
||||
task add 'project:Home & Garden' ... # Good
|
||||
task add project:Home\ \&\ Garden ... # Good
|
||||
task add project:Home' & 'Garden ... # Good
|
||||
task add project:Home \& Garden ... # Bad
|
||||
|
||||
The parser will not combine multiple arguments, for example:
|
||||
|
||||
task '/one two/' list # Good
|
||||
task /one two/ list # Bad
|
||||
task /'one two'/ list # Bad, unless ' is part of the pattern
|
||||
|
||||
3. By default, *no* calculations are made, unless the `:=` eval operator is
|
||||
used, and if so, the whole argument may need to be quoted or escaped to
|
||||
satisfy Rule 1.
|
||||
|
||||
task add project:3.project+x # Literal
|
||||
task add project:=3.project+x # DOM reference + concatenation
|
||||
|
||||
4. Bare word search terms are no longer supported. Use the pattern type
|
||||
argument instead.
|
||||
|
||||
task /foo/ list # Good
|
||||
task foo list # Bad
|
||||
|
||||
5. Expressions must be a series of arguments, not a quoted string.
|
||||
|
||||
task urgency \< 5.0 list # Good
|
||||
task 'urgency < 5.0 list' # Bad
|
||||
|
||||
|
||||
## Other Changes
|
||||
|
||||
Aside from the command line parser, there are other changes needed:
|
||||
|
||||
- Many online documents will need to be modified.
|
||||
|
||||
- Filters will be automatically parenthesized, so that every command line will
|
||||
now looke like:
|
||||
|
||||
task [overrides] [(cli-filter)] [(context-filter)] [(report-filter)] command [modifications]
|
||||
|
||||
- There will be more errors when the command line is not understood.
|
||||
|
||||
- Ambiguous ISO date formats are dropped.
|
||||
|
||||
YYYYMMDD # Bad
|
||||
YYYY-MM-DD # Good
|
||||
|
||||
hhmmss # Bad
|
||||
hh:mm:ss # Good
|
||||
|
||||
- The tutorial videos will be even more out of date, and will be replaced by a
|
||||
large number of smaller demo \'movies\'.
|
||||
444
docs/rfcs/client.md
Normal file
444
docs/rfcs/client.md
Normal file
|
|
@ -0,0 +1,444 @@
|
|||
---
|
||||
title: "Taskwarrior - Creating a Taskserver Client"
|
||||
---
|
||||
|
||||
|
||||
# Creating a Taskserver Client
|
||||
|
||||
A Taskserver client is a todo-list manager. It may be as simple as a program
|
||||
that captures a single task, as complex as Taskwarrior, or anything in between.
|
||||
It can be a mobile client, a web application, or any other type of program.
|
||||
|
||||
This document describes how such a client would interact with the server.
|
||||
|
||||
A client to the Taskserver is a program that manages a task list, and wishes to
|
||||
exchange data with the server so that the task list may be shared.
|
||||
|
||||
In order to do this, a client must store tasks locally, upload local changes,
|
||||
download remote changes, and apply remote changes to the local tasks.
|
||||
|
||||
The client must consider that there may be no network connectivity, or no desire
|
||||
by the user to synchronize.
|
||||
|
||||
The client will need proper credentials to talk to the server.
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
In this document, we adopt the convention discussed in Section 1.3.2 of
|
||||
[RFC1122](https://tools.ietf.org/html/rfc1122#page-16) of using the capitalized
|
||||
words MUST, REQUIRED, SHOULD, RECOMMENDED, MAY, and OPTIONAL to define the
|
||||
significance of each particular requirement specified in this document.
|
||||
|
||||
In brief: \"MUST\" (or \"REQUIRED\") means that the item is an absolute
|
||||
requirement of the specification; \"SHOULD\" (or \"RECOMMENDED\") means there
|
||||
may exist valid reasons for ignoring this item, but the full implications should
|
||||
be understood before doing so; and \"MAY\" (or \"OPTIONAL\") means that this
|
||||
item is optional, and may be omitted without careful consideration.
|
||||
|
||||
|
||||
## Taskserver Account
|
||||
|
||||
A Taskserver account must be created. This process creates a storage area, and
|
||||
generates the necessary credentials.
|
||||
|
||||
|
||||
## Credentials
|
||||
|
||||
A Taskserver client needs the following credentials in order to communicate with
|
||||
a server:
|
||||
|
||||
- Server address and port
|
||||
- Organization name
|
||||
- User name
|
||||
- Password
|
||||
- Certificate
|
||||
- Key
|
||||
|
||||
The server address and port are the network location of the server. An example
|
||||
of this value is:
|
||||
|
||||
foo.example.com:53589
|
||||
|
||||
In addition to a DNS name, this can be an IPv4 or IPv6 address.
|
||||
|
||||
The organization name is an arbitrary grouping, and is typically \'PUBLIC\',
|
||||
reflecting the individual nature of server accounts. Future capabilities will
|
||||
provide functionality that support groups of users, called an organization.
|
||||
|
||||
The user name is the full name. This will be the name used to identify other
|
||||
users in an organization, in a future release. Example \'John Doe\'.
|
||||
|
||||
The password is a text string generated by the server at account creation time.
|
||||
It should be considered a secret.
|
||||
|
||||
The certificate is an X.509 PEM file generated by the server at account creation
|
||||
time. This is used for authentication. It should be considered a secret.
|
||||
|
||||
The key is an X.509 PEM file generated by the server at account creation time.
|
||||
This is used for encryption. It should be considered a secret.
|
||||
|
||||
These credentials need to be stored on the client, and used during the sync
|
||||
operation.
|
||||
|
||||
|
||||
## Description of a Taskserver Client
|
||||
|
||||
This section describes how a client might behave in order to facilitate
|
||||
integration with the Taskserver.
|
||||
|
||||
|
||||
## Encryption
|
||||
|
||||
The Taskserver only communicates using encryption. Therefore all user data is
|
||||
encrypted while in transit. The Taskserver currently uses
|
||||
[GnuTLS](https://gnutls.org) to support this encryption, and therefore supports
|
||||
the following protocols:
|
||||
|
||||
- SSL 3.0
|
||||
- TLS 1.0
|
||||
- TLS 1.1
|
||||
- TLS 1.2
|
||||
|
||||
The client may use any library that supports the above.
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
The client needs to store configuration, which matches the credentials needed
|
||||
for Taskserver communication. See section 2.1 \"Credentials\".
|
||||
|
||||
The credentials may not be modified by the user without losing server access.
|
||||
|
||||
The server:port data may need to be changed automatically following a redirect
|
||||
response from the server. See section 5 \"Server Errors\".
|
||||
|
||||
|
||||
## Local Storage
|
||||
|
||||
The client needs to store task data locally. The client will need to be able to
|
||||
find tasks by their UUID and overwrite them. Uploaded and downloaded task
|
||||
changes will use the [Taskwarrior Data Interchange
|
||||
Format](/docs/design/task).
|
||||
|
||||
|
||||
## Local Changes
|
||||
|
||||
Whenever local data is modified, that change MUST be synced with the server. But
|
||||
this does not have to occur immediately, in fact the client SHOULD NOT assume
|
||||
connectivity at any time.
|
||||
|
||||
A client SHOULD NOT also assume that the server is available. If the server is
|
||||
not available, the local changes should be retained, and the sync operation
|
||||
repeated later.
|
||||
|
||||
Ideally the client will give the user full control over sync operations.
|
||||
Automatically syncing after all local modifications is not recommended. If a
|
||||
client performs too many sync operations, the server MAY revoke the certificate.
|
||||
|
||||
Effectively, the client should maintain a separate list of tasks changed since
|
||||
the last successful sync operation.
|
||||
|
||||
Note that tasks have a \"modified\" attribute, which should be updated whenever
|
||||
a change is made. This attribute contributes to conflict resolution on the
|
||||
server.
|
||||
|
||||
|
||||
## Remote Changes
|
||||
|
||||
When a server sends remote changes to a client, in the response to a sync
|
||||
request, the changes have already been merged by the server, and therefore the
|
||||
client should simply store them intact.
|
||||
|
||||
Based on the UUID in the task, the client can determine whether a task is new
|
||||
(and should be added to the local list of tasks), or whether it represents a
|
||||
modification (and should overwrite it\'s existing entry).
|
||||
|
||||
The client MUST NOT perform any merges.
|
||||
|
||||
|
||||
## Sync Key
|
||||
|
||||
Whenever a sync is performed, the server responds by sending a sync key and any
|
||||
remote changes. The sync key is important, and should be included in the next
|
||||
sync request. The client is REQUIRED to store the sync key in every server
|
||||
response message.
|
||||
|
||||
If a client omits the sync key in a sync message, the response will be a
|
||||
complete set of all tasks and modifications.
|
||||
|
||||
|
||||
## Data Integrity
|
||||
|
||||
Although a task is guaranteed to contain at least \'entry\', \'description\' and
|
||||
\'uuid\' attributes, it may also contain other known fields, and unknown
|
||||
user-defined fields. An example might be an attribute named \'estimate\'.
|
||||
|
||||
If a task is received via sync that contains an attribute named \'estimate\',
|
||||
then a client has the responsibility of preserving the attribute intact. If that
|
||||
data is shown, then it is assumed to be of type \'string\', which is the format
|
||||
used by JSON for all values.
|
||||
|
||||
Conversely, if a client wishes to add a custom attribute, it is guaranteed that
|
||||
the server and other clients will preserve that attribute.
|
||||
|
||||
Using this rule, two clients of differing capabilities can exchange data and
|
||||
still maintain custom attributes.
|
||||
|
||||
This is a requirement. Any client that does not obey this requirement is broken.
|
||||
|
||||
|
||||
## Synchronizing
|
||||
|
||||
Synchronizing with the Taskserver consists of a single transaction. Once an
|
||||
encrypted connection is made with the server, the client MUST compose a [sync
|
||||
request message](/docs/design/request). This message includes credentials
|
||||
and local changes. The response message contains status and remote changes,
|
||||
which MUST be stored locally.
|
||||
|
||||
|
||||
## Establishing Encrypted Connection
|
||||
|
||||
All communication with the Taskserver is encrypted using the certificate and key
|
||||
provided to each user. Using the \'server\' configuration setting, establish a
|
||||
connection.
|
||||
|
||||
|
||||
## Sync Request
|
||||
|
||||
See [sync request message](/docs/design/request). A sync request MUST
|
||||
contain a sync key if one was provided by a previous sync. A sync request MUST
|
||||
contain a list of modified tasks, in JSON format (see [Task
|
||||
JSON](/docs/design/task)), if local modifications have been made.
|
||||
|
||||
|
||||
## Sync Response
|
||||
|
||||
A sync response WILL contain a \'code\' and \'status\' header variable, WILL
|
||||
contain a sync key in the payload, and MAY contain a list of tasks from the
|
||||
server in JSON format (see [Task JSON](/docs/design/task)).
|
||||
|
||||
|
||||
## Server Messages
|
||||
|
||||
There are cases when the server needs to inform the user of some condition. This
|
||||
may be anticipated server downtime, for example. The response message is
|
||||
typically not present, but may be present in the header, containing a string:
|
||||
|
||||
...
|
||||
message: Scheduled maintenance 2013-07-14 08:00UTC for 10 minutes.
|
||||
...
|
||||
|
||||
If such a message is returned by the server, it SHOULD be made available to the
|
||||
user. This is a recommendation, not a requirement.
|
||||
|
||||
|
||||
## Server Errors
|
||||
|
||||
The server may generate many errors (See
|
||||
[Protocol](/docs/design/protocol)), but the following is a list of the ones
|
||||
most in need of special handling:
|
||||
|
||||
- 200 Success
|
||||
- 201 No change
|
||||
- 301 Redirect
|
||||
- 430 Access denied
|
||||
- 431 Account suspended
|
||||
- 432 Account terminated
|
||||
- 5xx Error
|
||||
|
||||
The 200 indicates success, and that a change was recorded. The 201 indicates
|
||||
success but no changes were necessary. The 301 is a redirect message indicating
|
||||
that the client MUST re-request from a new server. The 43x series messages are
|
||||
account-related. Any 5xx series code is a server error of some kind. All errors
|
||||
consist of a code and a status message:
|
||||
|
||||
code: 200
|
||||
status: Success
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
Here are examples of properly formatted request and response messages. Note that
|
||||
the messages are indented for clarity in this document, but is not the case in a
|
||||
properly formatted message. Also note that newline characters U+000D are not
|
||||
shown, but are implied by the separate lines. Because some messages have
|
||||
trailing newline characters, the text is delimited by the \'cut\' markers:
|
||||
|
||||
foo
|
||||
|
||||
The example above illustrates text consisting of:
|
||||
|
||||
U+0066 f
|
||||
U+006F o
|
||||
U+006F o
|
||||
U+000D newline
|
||||
U+000D newline
|
||||
|
||||
Note that these values are left unspecified, but should be clear from the
|
||||
context, and the [message format](/docs/design/request) spec:
|
||||
|
||||
<size>
|
||||
<organization>
|
||||
<user>
|
||||
<password>
|
||||
|
||||
|
||||
## First Sync
|
||||
|
||||
The first time a client syncs, there is (perhaps) no data to upload, and no sync
|
||||
key from a previous sync.
|
||||
|
||||
<size>type: sync
|
||||
org: <organization>
|
||||
user: <user>
|
||||
key: <password>
|
||||
client: task 2.3.0
|
||||
protocol: v1
|
||||
|
||||
Note the double newline character separating header from payload, with an empty
|
||||
payload.
|
||||
|
||||
|
||||
## Request: Sync No Data
|
||||
|
||||
Ordinarily when a client syncs, there is a sync key from the previous sync
|
||||
response to send. This example shows a sync with no local changes, but a sync
|
||||
key from a previous sync.
|
||||
|
||||
<size>type: sync
|
||||
org: <organization>
|
||||
user: <user>
|
||||
key: <password>
|
||||
client: task 2.3.0
|
||||
protocol: v1
|
||||
|
||||
2e4685f8-34bc-4f9b-b7ed-399388e182e1
|
||||
|
||||
|
||||
## Request: Sync Data
|
||||
|
||||
This sync request shows a sync key from the previous sync, and a locally
|
||||
modified task.
|
||||
|
||||
<size>type: sync
|
||||
org: <organization>
|
||||
user: <user>
|
||||
key: <password>
|
||||
client: task 2.3.0
|
||||
protocol: v1
|
||||
|
||||
2e4685f8-34bc-4f9b-b7ed-399388e182e1
|
||||
{"description":"An example","uuid":"8ad2e3db-914d-4832-b0e6-72fa04f6e331",...}
|
||||
|
||||
|
||||
## Response: No Data
|
||||
|
||||
If a sync results in no downloads to the client, the response will look like
|
||||
this.
|
||||
|
||||
<size>type: response
|
||||
client: taskd 1.0.0
|
||||
protocol: v1
|
||||
code: 200
|
||||
status: Ok
|
||||
|
||||
45da7110-1bcc-4318-d33e-12267a774e0f
|
||||
|
||||
Note that there is a sync key which must be stored and used in the next sync
|
||||
request, but there are no remote changes to store.
|
||||
|
||||
|
||||
## Response: Remote Data
|
||||
|
||||
This shows a sync response providing a new sync key, and a remote change to two
|
||||
tasks.
|
||||
|
||||
<size>type: response
|
||||
client: taskd 1.0.0
|
||||
protocol: v1
|
||||
code: 200
|
||||
status: Ok
|
||||
|
||||
45da7110-1bcc-4318-d33e-12267a774e0f
|
||||
{"description":"Test data","uuid":"8ad2e3db-914d-4832-b0e6-72fa04f6e331",...}
|
||||
{"description":"Test data2","uuid":"3b6218f9-726a-44fc-aa63-889ff52be442",...}
|
||||
|
||||
Note that the sync key must be stored for the next sync request.
|
||||
|
||||
Note that the two changed tasks must be stored locally, and if the UUID in the
|
||||
tasks matches local tasks, then the local tasks must be overwritten.
|
||||
|
||||
|
||||
## Response: Error
|
||||
|
||||
<size>type: response
|
||||
client: taskd 1.0.0
|
||||
protocol: v1
|
||||
code: 431
|
||||
status: Account suspended
|
||||
|
||||
Note the double newline character separating header from payload, with an empty
|
||||
payload.
|
||||
|
||||
|
||||
## Response: Relocate
|
||||
|
||||
<size>type: response
|
||||
client: taskd 1.0.0
|
||||
protocol: v1
|
||||
code: 301
|
||||
status: Redirect
|
||||
info:
|
||||
|
||||
Note the \'info\' field will contain a \':\' string that should be used for all
|
||||
future sync requests. This indicates that a user account was moved to another
|
||||
server.
|
||||
|
||||
Note the double newline character separating header from payload, with an empty
|
||||
payload.
|
||||
|
||||
|
||||
## Response: Message
|
||||
|
||||
Occasionally the server will need to convey a message, and will include an
|
||||
additional header variable containing that message.
|
||||
|
||||
The server [protocol](/docs/design/protocol) states that the message SHOULD
|
||||
be shown to the user. This message will be used for system event messages, used
|
||||
rarely, and never used for advertising or promotion.
|
||||
|
||||
<size>type: response
|
||||
client: taskd 1.0.0
|
||||
protocol: v1
|
||||
code: 200
|
||||
status: Ok
|
||||
message: Scheduled maintenance 2013-07-14 08:00UTC for 10 minutes.
|
||||
|
||||
45da7110-1bcc-4318-d33e-12267a774e0f
|
||||
|
||||
Note that the same message will likely be included in consecutive responses.
|
||||
|
||||
|
||||
## Reference Implementation
|
||||
|
||||
The Taskserver 1.1.0 codebase contains a reference implementation of an SSL/TLS
|
||||
client and server program, which communicate text strings.
|
||||
|
||||
taskd.git/src/tls/Makefile # To build the example
|
||||
taskd.git/src/tls/README # How to run the example
|
||||
taskd.git/src/tls/TLSClient.cpp # TLS client code
|
||||
taskd.git/src/tls/TLSClient.h
|
||||
taskd.git/src/tls/TLSServer.cpp # TLS Server code
|
||||
taskd.git/src/tls/TLSServer.h
|
||||
taskd.git/src/tls/c.cpp # Client program
|
||||
taskd.git/src/tls/s.cpp # Server program
|
||||
taskd.git/src/tls/text.cpp # Text manipulation
|
||||
taskd.git/src/tls/text.h # Text manipulation
|
||||
|
||||
The Taskwarrior codebase, version 2.4.0, is the reference implementation.
|
||||
|
||||
task.git/src/TLSClient.cpp # TLS client code
|
||||
task.git/src/TLSClient.h
|
||||
task.git/src/commands/CmdSync.cpp # Sync implementation
|
||||
task.git/src/commands/CmdSync.h
|
||||
259
docs/rfcs/dom.md
Normal file
259
docs/rfcs/dom.md
Normal file
|
|
@ -0,0 +1,259 @@
|
|||
---
|
||||
title: "Taskwarrior - Full DOM Support"
|
||||
---
|
||||
|
||||
## Work in Progress
|
||||
|
||||
This design document is a work in progress, and subject to change. Once
|
||||
finalized, the feature will be scheduled for an upcoming release.
|
||||
|
||||
|
||||
# Full DOM Support
|
||||
|
||||
Taskwarrior currently supports DOM references that can access any stored data
|
||||
item. The general forms supported are:
|
||||
|
||||
[ <id> | <uuid> ] <attribute> [ <part> ]
|
||||
|
||||
Examples include:
|
||||
|
||||
due
|
||||
123.uuid
|
||||
entry.month
|
||||
123.annotations.0.entry.year
|
||||
a87bc10f-931b-4558-a44a-e901a77db011.description
|
||||
|
||||
Additionally there are references for accessing configuration and system/program
|
||||
level items.
|
||||
|
||||
rc.<name>
|
||||
context.program
|
||||
context.args
|
||||
context.width
|
||||
context.height
|
||||
system.version
|
||||
system.os
|
||||
|
||||
While this is adequate for data retrieval, we have the possibility of extending
|
||||
it further to include data formats, higher-level constructs, and then to make
|
||||
use of DOM references in more locations. This contributes to our goal of
|
||||
simplifying Taskwarrior.
|
||||
|
||||
|
||||
## Proposed Format Support
|
||||
|
||||
When defining a custom report, the columns shown are defined like this:
|
||||
|
||||
report.x.columns=uuid.short,description.oneline ...
|
||||
|
||||
This syntax is:
|
||||
|
||||
<attribute> [ . <format> ]
|
||||
|
||||
If no `format` is specified, then `default` is assumed. The src/columns/ColΧ\*
|
||||
objects are responsible for supporting and rendering these formats. There is
|
||||
currently no consistency among these formats based on data type.
|
||||
|
||||
By incorporating formats into DOM references, we eliminate the need for a
|
||||
separate syntax for custom reports, and provide this:
|
||||
|
||||
123.due.iso
|
||||
123.due.month.short
|
||||
123.uuid.short
|
||||
|
||||
A standard set of formats per data type would be:
|
||||
|
||||
Type
|
||||
|
||||
Formats
|
||||
|
||||
Example
|
||||
|
||||
Numeric
|
||||
|
||||
default
|
||||
|
||||
`123 `
|
||||
|
||||
indicator
|
||||
|
||||
Based on `rc.<attribute>.indicator` which overrides `rc.numeric.indicator`.
|
||||
|
||||
json
|
||||
|
||||
`"<attribute>":"<value>"`
|
||||
|
||||
String
|
||||
|
||||
default
|
||||
|
||||
Buy milk
|
||||
|
||||
short
|
||||
|
||||
Feb
|
||||
|
||||
indicator
|
||||
|
||||
Based on `rc.<attribute>.indicator` which overrides `rc.string.indicator`.
|
||||
|
||||
json
|
||||
|
||||
`"<attribute>":"<value>"`
|
||||
|
||||
Date
|
||||
|
||||
default
|
||||
|
||||
Based on `rc.dateformat`
|
||||
|
||||
iso
|
||||
|
||||
2017-02-20T09:02:12
|
||||
|
||||
julian
|
||||
|
||||
2457805.12858
|
||||
|
||||
epoch
|
||||
|
||||
1234567890
|
||||
|
||||
age
|
||||
|
||||
2min
|
||||
|
||||
relative
|
||||
|
||||
-2min
|
||||
|
||||
remaining
|
||||
|
||||
0:02:04
|
||||
|
||||
countdown
|
||||
|
||||
0:02:04
|
||||
|
||||
indicator
|
||||
|
||||
Based on `rc.<attribute>.indicator` which overrides `rc.date.indicator`.
|
||||
|
||||
json
|
||||
|
||||
`"<attribute>":"<value>"`
|
||||
|
||||
Duration
|
||||
|
||||
default
|
||||
|
||||
1wk
|
||||
|
||||
iso
|
||||
|
||||
P1W
|
||||
|
||||
indicator
|
||||
|
||||
Based on `rc.<attribute>.indicator` which overrides `rc.duration.indicator`.
|
||||
|
||||
json
|
||||
|
||||
`"<attribute>":"<value>"`
|
||||
|
||||
There will also be a set of attribute-specific formats, similar to the currently
|
||||
supported set:
|
||||
|
||||
depends.list
|
||||
depends.count
|
||||
description.combined
|
||||
description.desc
|
||||
description.oneline
|
||||
description.truncated
|
||||
description.count
|
||||
description.truncated_count
|
||||
parent.default|long
|
||||
parent.short
|
||||
project.full
|
||||
project.parent
|
||||
project.indented
|
||||
status.default|long
|
||||
status.short
|
||||
tags.default|list
|
||||
tags.count
|
||||
urgency.default|real
|
||||
urgency.integer
|
||||
uuid.default|long
|
||||
uuid.short
|
||||
|
||||
Custom report sort criteria will also use DOM references. This will be augmented
|
||||
by the `+`/`-` sort direction and `/` break indicator, which are not part of the
|
||||
DOM.
|
||||
|
||||
|
||||
## High Level Construct Support
|
||||
|
||||
There need to be read-only DOM references that do not correspond directly to
|
||||
stored attributes. Tasks have emergent properties represented by virtual tags,
|
||||
which will be accessible, in this case returning a `0` or `1`:
|
||||
|
||||
123.tags.OVERDUE
|
||||
|
||||
Using `rc.due` and the `due` attribute, the `OVERDUE` virtual tag is a
|
||||
combination of the two. Other examples may include:
|
||||
|
||||
task.syncneeded
|
||||
task.pending.count
|
||||
task.hooks.installed
|
||||
|
||||
|
||||
## Writable References
|
||||
|
||||
When a DOM reference refers to an attribute or RC setting, and does not extend
|
||||
further and reference a component or format, it may be writable. For example:
|
||||
|
||||
rc.hooks # writable
|
||||
123.description # writable
|
||||
123.entry.month # not writable, not an attribute
|
||||
|
||||
|
||||
## Data Interchange
|
||||
|
||||
The export command can be used to show a filtered set of tasks in JSON format,
|
||||
and this will also be available as a DOM format:
|
||||
|
||||
123.json
|
||||
a87bc10f-931b-4558-a44a-e901a77db011.json
|
||||
|
||||
|
||||
## RC File Support
|
||||
|
||||
The RC file (`~/.taskrc`) will support DOM references in values. This will form
|
||||
a late-bound reference, which is evaluated at runtime, every time.
|
||||
|
||||
An example is to make two reports share the same description:
|
||||
|
||||
$ task config -- report.ls.description rc.report.list.description
|
||||
|
||||
This sets the description for the `ls` report to be a reference to the
|
||||
description of the `list` report. This reference is not evaluated when the entry
|
||||
is written, but is evaluated every time the value is read, thus providing
|
||||
late-bound behavior. Then if the description of the `list` report changes, so
|
||||
does that of the `ls` report automatically.
|
||||
|
||||
|
||||
## Implementation Details
|
||||
|
||||
These notes list a series of anticipated changes to the codebase.
|
||||
|
||||
- The `src/columns/Col*` objects will implement type-specific and
|
||||
attribute-specific DOM support. DOM reference lookup will defer to the
|
||||
column objects first.
|
||||
- Some DOM references will be writable, permitting a `_set` command to
|
||||
complement the `_get` command.
|
||||
- The `Config` object will recognize DOM references in values and perform
|
||||
lookup at read time. This will require circularity detection.
|
||||
- `src/DOM.cpp` will provide a memoized function to determine whether a DOM
|
||||
reference is valid.
|
||||
- `src/DOM.cpp` will provide a function to obtain a DOM reference value, with
|
||||
supporting metadata (type, writable).
|
||||
436
docs/rfcs/plans.md
Normal file
436
docs/rfcs/plans.md
Normal file
|
|
@ -0,0 +1,436 @@
|
|||
---
|
||||
title: "Plans"
|
||||
---
|
||||
|
||||
There are many interconnected features and technologies in Taskwarrior,
|
||||
Taskserver, Tasksh and Timewarrior, each piece having it's own goals.
|
||||
|
||||
This matrix allows a simple reading of where things are, and where they are
|
||||
going. This is a low-resolution time line. It is subject to change. It does not
|
||||
constitute a concrete plan. This is an all-volunteer effort, and scheduling is
|
||||
difficult.
|
||||
|
||||
[Last updated 2016-08-08.]
|
||||
|
||||
<table class="table table-bordered table-striped">
|
||||
<tr>
|
||||
<th>Taskwarrior<br />Technology/Feature</th>
|
||||
<th>
|
||||
<span class="label label-success">2.5.1</span><br />
|
||||
Current<br /><br />
|
||||
Released 2016-02-24
|
||||
</th>
|
||||
<th>
|
||||
<span class="label label-danger">2.6.0</span><br />
|
||||
Next<br /><br />
|
||||
2017
|
||||
</th>
|
||||
<th>
|
||||
<span class="label label-info">2.x</span><br />
|
||||
Future
|
||||
</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Core</td>
|
||||
<td>
|
||||
<a href="/docs/dom.html">DOM</a><br />
|
||||
Filters<br />
|
||||
Expressions<br />
|
||||
Color Rules<br />
|
||||
Custom Reports<br />
|
||||
Annotations<br />
|
||||
Tags / Virtual Tags<br />
|
||||
<a href="/docs/context.html">Context</a><br />
|
||||
</td>
|
||||
<td>
|
||||
<a href="/docs/design/recurrence.html">Recurrence</a><br />
|
||||
Shared library<br />
|
||||
<code>purge</code> command<br />
|
||||
</td>
|
||||
<td>
|
||||
True Color
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>API</td>
|
||||
<td>
|
||||
<a href="/docs/design/task.html">JSON</a><br />
|
||||
Import<br />
|
||||
Export<br />
|
||||
<a href="/docs/hooks.html">Hooks</a><br />
|
||||
<a href="/docs/hooks2.html">Hooks v2</a><br />
|
||||
<a href="/docs/dom.html">DOM</a><br />
|
||||
Helper commands<br />
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
<td>
|
||||
<code>on-sync</code> hook<br />
|
||||
Full DOM<br />
|
||||
DOM access in rc<br />
|
||||
<code>$ENV</code> access in rc<br />
|
||||
Report columns as DOM refs<br />
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>
|
||||
Attributes<br />
|
||||
<a href="/docs/udas.html">User Defined Attributes (UDA)</a>
|
||||
</td>
|
||||
<td>
|
||||
<code>modified</code><br />
|
||||
<code>priority</code> as a UDA<br />
|
||||
</td>
|
||||
<td>
|
||||
<code>template</code><br />
|
||||
<code>rtype</code><br />
|
||||
Remove <code>mask</code><br />
|
||||
Remove <code>imask</code><br />
|
||||
Remove <code>parent</code><br />
|
||||
</td>
|
||||
<td>
|
||||
<code>org</code><br />
|
||||
<code>group</code><br />
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Reports</td>
|
||||
<td>
|
||||
Improved layouts<br />
|
||||
Improved Themes
|
||||
</td>
|
||||
<td>
|
||||
Daily, Weekly reports (history, ghistory)<br />
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Synchronization</td>
|
||||
<td>
|
||||
<code>task sync</code><br />
|
||||
<code>task sync init</code> (all tasks)<br />
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
<td>
|
||||
<code>task sync reset</code><br />
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>TDB (task database)</td>
|
||||
<td>
|
||||
Local file locking<br />
|
||||
Single file set<br />
|
||||
Single user
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
<td>
|
||||
Threaded file load<br />
|
||||
Read-only mode
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>I18N / L10N</td>
|
||||
<td>
|
||||
UTF-8 support<br />
|
||||
<code>deu-DEU</code><br />
|
||||
<code>eng-USA</code><br />
|
||||
<code>epo-RUS</code><br />
|
||||
<code>esp-ESP</code><br />
|
||||
<code>fra-FRA</code><br />
|
||||
<code>ita-ITA</code><br />
|
||||
<code>pol-POL</code><br />
|
||||
<code>por-PRT</code><br />
|
||||
</td>
|
||||
<td>
|
||||
No I18N / L10N
|
||||
</td>
|
||||
<td>
|
||||
Migrate to <a href="https://www.gnu.org/software/gettext/">gettext</a><br />
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Documentation</td>
|
||||
<td>
|
||||
man: task<br />
|
||||
man: taskrc<br />
|
||||
man: task-color<br />
|
||||
man: task-sync<br />
|
||||
youtube: various<br />
|
||||
<a href="https://taskwarrior.org">taskwarrior.org</a><br />
|
||||
taskwarrior.com: Support Site<br />
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
<td>
|
||||
New video tutorials<br />
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Testing</td>
|
||||
<td>
|
||||
C++ tests<br />
|
||||
Python tests<br />
|
||||
Sync tests<br />
|
||||
Parallel tests<br />
|
||||
</td>
|
||||
<td>
|
||||
Migration to Flod2<br />
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Tool Chain</td>
|
||||
<td>
|
||||
GCC 4.7 / Clang 3.3<br />
|
||||
C++11 support<br />
|
||||
CMake<br />
|
||||
</td>
|
||||
<td>
|
||||
GCC 4.9 / Clang 3.4<br />
|
||||
Full C++11 support<br />
|
||||
</td>
|
||||
<td>
|
||||
Full C++14 support<br />
|
||||
Full C++17 support<br />
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<table class="table table-bordered table-striped">
|
||||
<tr>
|
||||
<th>Tasksh<br />Technology/Feature</th>
|
||||
<th>
|
||||
<span class="label label-success">1.1.0</span><br />
|
||||
Current<br /><br />
|
||||
Released 2016-09-05
|
||||
</th>
|
||||
<th>
|
||||
<span class="label label-danger">1.2.0</span><br />
|
||||
Next<br /><br />
|
||||
2017
|
||||
</th>
|
||||
<th>
|
||||
<span class="label label-info">1.x</span><br />
|
||||
Future
|
||||
</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Core</td>
|
||||
<td>
|
||||
<a href="/docs/review.html">Review</a><br />
|
||||
libreadline<br />
|
||||
Shared library<br />
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
<td>
|
||||
Pomodoro timer<br />
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Tool Chain</td>
|
||||
<td>
|
||||
CMake<br />
|
||||
GCC 4.7 / Clang 3.3<br />
|
||||
</td>
|
||||
<td>
|
||||
GCC 4.9 / Clang 3.4<br />
|
||||
Full C++11 support<br />
|
||||
</td>
|
||||
<td>
|
||||
Full C++14 support<br />
|
||||
Full C++17 support<br />
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<table class="table table-bordered table-striped">
|
||||
<tr>
|
||||
<th>Taskserver<br />Technology/Feature</th>
|
||||
<th>
|
||||
<span class="label label-success">1.1.0</span><br />
|
||||
Current<br /><br />
|
||||
Released 2015-05-10
|
||||
</th>
|
||||
<th>
|
||||
<span class="label label-danger">1.2.0</span><br />
|
||||
Next<br /><br />
|
||||
2017
|
||||
</th>
|
||||
<th>
|
||||
<span class="label label-info">1.x</span><br />
|
||||
Future
|
||||
</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Core</td>
|
||||
<td>
|
||||
Serial server
|
||||
</td>
|
||||
<td>
|
||||
Shared library<br />
|
||||
</td>
|
||||
<td>
|
||||
Threaded server
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Protocol</td>
|
||||
<td>
|
||||
v1
|
||||
</td>
|
||||
<td>
|
||||
v1.1 - client reset request<br />
|
||||
</td>
|
||||
<td>
|
||||
v1.2
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>DB (Data Storage)</td>
|
||||
<td>
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
<td>
|
||||
GC
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Security</td>
|
||||
<td>
|
||||
Validation
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
<td>
|
||||
UUID:Cert Verification<br />
|
||||
Combined Certs
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Tool Chain</td>
|
||||
<td>
|
||||
GCC 4.7 / Clang 3.3<br />
|
||||
CMake<br />
|
||||
</td>
|
||||
<td>
|
||||
GCC 4.9 / Clang 3.4<br />
|
||||
Full C++11 support<br />
|
||||
</td>
|
||||
<td>
|
||||
Full C++14 support<br />
|
||||
Full C++17 support<br />
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
<table class="table table-bordered table-striped">
|
||||
<tr>
|
||||
<th>Timewarrior<br />Technology/Feature</th>
|
||||
<th>
|
||||
<span class="label label-success">1.0.0</span><br />
|
||||
Current<br /><br />
|
||||
Released 2016-08-20
|
||||
</th>
|
||||
<th>
|
||||
<span class="label label-danger">1.1.0</span><br />
|
||||
Next<br /><br />
|
||||
2017
|
||||
</th>
|
||||
<th>
|
||||
<span class="label label-info">1.x</span><br />
|
||||
Future
|
||||
</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Core</td>
|
||||
<td>
|
||||
Shared library<br />
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
<td>
|
||||
True Color
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Reports</td>
|
||||
<td>
|
||||
<code>summary</code> report<br />
|
||||
<code>gaps</code> report<br />
|
||||
<code>day</code> chart<br />
|
||||
<code>week</code> chart<br />
|
||||
<code>month</code> chart<br />
|
||||
<code>totals.py</code> extension<br />
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Rules</td>
|
||||
<td>
|
||||
Simple configuration rules
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
<td>
|
||||
Rule System<br />
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Integration</td>
|
||||
<td>
|
||||
Taskwarrior <code>on-modify</code> hook script
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
<td>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Tool Chain</td>
|
||||
<td>
|
||||
CMake<br />
|
||||
GCC 4.7 / Clang 3.3<br />
|
||||
C++11 support<br />
|
||||
</td>
|
||||
<td>
|
||||
GCC 4.9 / Clang 3.4<br />
|
||||
Full C++11 support<br />
|
||||
</td>
|
||||
<td>
|
||||
Full C++14 support<br />
|
||||
Full C++17 support<br />
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
211
docs/rfcs/protocol.md
Normal file
211
docs/rfcs/protocol.md
Normal file
|
|
@ -0,0 +1,211 @@
|
|||
---
|
||||
title: "Taskwarrior - Sync Protocol"
|
||||
---
|
||||
|
||||
|
||||
# Sync Protocol
|
||||
|
||||
|
||||
## Introduction
|
||||
|
||||
Taskwarrior data has typically been shared in several ways. Those include SCM
|
||||
(source code management) systems, directory synchronizing software (such as
|
||||
DropBox), and by use of the \'push\', \'pull\' and \'merge\' commands introduced
|
||||
in version 1.9.3.
|
||||
|
||||
While these methods work, they each have problems associated with the merging of
|
||||
data. In the case of directory synchronizing software, there is no merging at
|
||||
all - just simple file overwrite, despite many people believing that the data is
|
||||
somehow combined and preserved.
|
||||
|
||||
The Taskserver is a solution. It is an online/cloud storage and sync service for
|
||||
taskwarrior data. It performs conflict-free data merging, and minimizes
|
||||
bandwidth use.
|
||||
|
||||
The Taskserver also provides multi-client access, so that a task added using a
|
||||
web client could be immediately viewed using a mobile client, or modified using
|
||||
taskwarrior. Choice of clients is important - people have widely varying
|
||||
behaviors and tastes.
|
||||
|
||||
The Taskserver also provides multi-user access, which introduces new
|
||||
capabilities, such as list sharing and delegation. These will require later
|
||||
modification to this protocol.
|
||||
|
||||
The Taskserver protocol will be implemented by the taskd project and first used
|
||||
in taskwarrior 2.3.0. Other clients will follow.
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
In this document, we adopt the convention discussed in Section 1.3.2 of
|
||||
[RFC1122](https://tools.ietf.org/html/rfc1122#page-16) of using the capitalized
|
||||
words MUST, REQUIRED, SHOULD, RECOMMENDED, MAY, and OPTIONAL to define the
|
||||
significance of each particular requirement specified in this document.
|
||||
|
||||
In brief: \"MUST\" (or \"REQUIRED\") means that the item is an absolute
|
||||
requirement of the specification; \"SHOULD\" (or \"RECOMMENDED\") means there
|
||||
may exist valid reasons for ignoring this item, but the full implications should
|
||||
be understood before doing so; and \"MAY\" (or \"OPTIONAL\") means that this
|
||||
item is optional, and may be omitted without careful consideration.
|
||||
|
||||
|
||||
## Link Level
|
||||
|
||||
The Taskserver protocol assumes a reliable data stream such as provided by TCP.
|
||||
When TCP is used, a Taskserver listens on a single predetermined port *for the
|
||||
given client* only. This means the server may be using multiple ports to serve
|
||||
distinct sets of clients.
|
||||
|
||||
This server is only an interface between programs and the task data. It does not
|
||||
perform any user interaction or presentation-level functions.
|
||||
|
||||
|
||||
## Transactions
|
||||
|
||||
Each transaction is a single incoming message, with a single response message.
|
||||
All communication therefore consists of a single \'send\', followed by a single
|
||||
\'receive\', then termination. There are no sessions, and no continuously open
|
||||
connections. The message format is described in the [Taskserver Message
|
||||
Format](/docs/design/request) document.
|
||||
|
||||
|
||||
## Responsibilities of the Server
|
||||
|
||||
The server will maintain a set of transactions, in the original sequence,
|
||||
punctuated by sync keys which are UUIDs. Each sync key represents a non- trivial
|
||||
sync operation by a client. Each transaction is a [JSON-formatted
|
||||
task](/docs/design/task), followed by a newline (\\n) character. The result
|
||||
is a single file that contains interleaved lines of two types: tasks and sync
|
||||
keys.
|
||||
|
||||
This design allows the server to maintain a set of deltas such that multiple
|
||||
clients may request a minimal set of changes since their last sync.
|
||||
|
||||
|
||||
## Responsibilities of the Client
|
||||
|
||||
This describes how Taskwarrior implements sync.
|
||||
|
||||
All modifications to tasks (add, modify, done, delete \...) are recorded in the
|
||||
form of a fully-composed [JSON-formatted task](/docs/design/task). The
|
||||
formatted task is added to a local backlog.data file. If a task is modified a
|
||||
second time, it is added again to the backlog.data file - the lines are not
|
||||
combined. Each task SHALL have a \'modified\' date attribute that will help
|
||||
resolve conflicts.
|
||||
|
||||
On sync:
|
||||
|
||||
- Send a \'sync\' type message with the entire contents of the backlog.data,
|
||||
unmodified, as the message payload.
|
||||
- Receive one of the following response codes:
|
||||
- 201: This means \'no change\', and there is no further action to be
|
||||
taken.
|
||||
- 200: This means \'success\', and the message payload contains a set of
|
||||
tasks and a sync key:
|
||||
- The formatted tasks are to be stored as-is. These tasks will either
|
||||
be appended to the client data or will overwrite existing client
|
||||
data, based on the UUID of the task. No merge logic is necessary.
|
||||
- The sync key will be written to the backlog.data file, overwriting
|
||||
the previous contents, such that it will now contain only one line.
|
||||
- 301: Redirect to : found in the \'info\' response header, will force the
|
||||
client to resubmit the request to the new server.
|
||||
- 3xx, 4xx, 5xx: The \'status\' field contains an error message.
|
||||
- If the response contained any error or warning, the error should be shown to
|
||||
the user. This provides an opportunity for the server to announce downtime,
|
||||
or relocation.
|
||||
|
||||
If no sync key is sent, the server cannot provide an incremental delta, and so
|
||||
will send all task data, which should be stored as above. This should be the
|
||||
case for a client making its first sync call.
|
||||
|
||||
If an unrecognized attribute is present in the task data, the client MUST
|
||||
preserve the attribute unmodified, and assume it is of type \'string\'. This
|
||||
permits individual clients to augment the task data without other clients
|
||||
stripping it meaningful data. This is how UDAs (user defined attributes) are
|
||||
handled.
|
||||
|
||||
|
||||
## Extensions
|
||||
|
||||
This protocol was designed so that extensions to the protocol will take the form
|
||||
of additional message types and status codes.
|
||||
|
||||
|
||||
## Summary of Response Codes
|
||||
|
||||
Status responses indicate the server\'s response to the last command received
|
||||
from the client. The codes consist of a 3 digit numeric code.
|
||||
|
||||
The first digit of the response broadly indicates the success, failure, or
|
||||
progress of the previous command (based generally on
|
||||
[RFC640](https://tools.ietf.org/html/rfc640)
|
||||
[RFC821](https://tools.ietf.org/html/rfc821)):
|
||||
|
||||
----- -------------------------------------
|
||||
1yz Positive Preliminary reply
|
||||
2yz Positive Completion reply
|
||||
3yz Positive Intermediate reply
|
||||
4yz Transient Negative Completion reply
|
||||
5yz Permanent Negative Completion reply
|
||||
----- -------------------------------------
|
||||
|
||||
The next digit in the code indicates the response category:
|
||||
|
||||
----- -------------------------------------------------
|
||||
x0z Syntax
|
||||
x1z Information (e.g., help)
|
||||
x2z Connections
|
||||
x3z Authentication
|
||||
x4z Unspecified as yet
|
||||
x5z Taskd System (\...)
|
||||
x8z Nonstandard (private implementation) extensions
|
||||
----- -------------------------------------------------
|
||||
|
||||
A summary of all status response are:
|
||||
|
||||
----- -----------
|
||||
200 Success
|
||||
201 No change
|
||||
----- -----------
|
||||
|
||||
----- ----------------------------------------------------------------------------------------------------------------------------------------------
|
||||
300 Deprecated message type. This message will not be supported in future Taskserver releases.
|
||||
301 Redirect. Further requests should be made to the specified server/port.
|
||||
302 Retry. The client is requested to wait and retry the same request. The wait time is not specified, and further retry responses are possible.
|
||||
----- ----------------------------------------------------------------------------------------------------------------------------------------------
|
||||
|
||||
----- ------------------------------------------
|
||||
400 Malformed data
|
||||
401 Unsupported encoding
|
||||
420 Server temporarily unavailable
|
||||
421 Server shutting down at operator request
|
||||
430 Access denied
|
||||
431 Account suspended
|
||||
432 Account terminated
|
||||
----- ------------------------------------------
|
||||
|
||||
----- -----------------------------------
|
||||
500 Syntax error in request
|
||||
501 Syntax error, illegal parameters
|
||||
502 Not implemented
|
||||
503 Command parameter not implemented
|
||||
504 Request too big
|
||||
----- -----------------------------------
|
||||
|
||||
|
||||
## Security Considerations
|
||||
|
||||
All communication with the Taskserver uses SSL 3.0 or TLS 1.0, 1.1 or 1.2.
|
||||
Encryption is mandatory. Data is never transmitted in plain text.
|
||||
|
||||
|
||||
## Limitations and Guidelines
|
||||
|
||||
Some limitations exists to reduce bandwidth and load on the server. They are:
|
||||
|
||||
- A client may only connect to a single server. Synchronization among a set of
|
||||
servers is not supported.
|
||||
- A client should attempt to minimize data bandwidth usage by maintaining a
|
||||
local data store, and properly using sync keys.
|
||||
- A client should minimize data transfers by limiting the frequency of sync
|
||||
requests.
|
||||
203
docs/rfcs/recurrence.md
Normal file
203
docs/rfcs/recurrence.md
Normal file
|
|
@ -0,0 +1,203 @@
|
|||
---
|
||||
title: "Taskwarrior - Recurrence"
|
||||
---
|
||||
|
||||
# Draft
|
||||
|
||||
This is a draft design document. Your
|
||||
[feedback](mailto:support@taskwarrior.org?Subject=Feedback) is welcomed.
|
||||
|
||||
Recurrence
|
||||
----------
|
||||
|
||||
Recurrence needs an overhaul to improve weaknesses and add new features.
|
||||
|
||||
# Terminology
|
||||
|
||||
- The hidden 'parent' task is called the template.
|
||||
- Synthesis is the name for the generation of new recurring task instances
|
||||
when necessary.
|
||||
- The synthesized tasks are called instances.
|
||||
- The index is the zero-based monotonically increasing number of the instance.
|
||||
- Drift is the accumulated errors in time that cause a due date to slowly
|
||||
change for each recurring task.
|
||||
|
||||
# Criticism of Current Implementation
|
||||
|
||||
- The `mask` attribute grows unbounded.
|
||||
- Only strict recurrence cycles are supported. The example of mowing the lawn
|
||||
is that you want to mow the lawn every seven days, but when you are four
|
||||
days late mowing the lawn, the next mowing should be in seven days, not in
|
||||
three.
|
||||
- Intances generated on one machine and then synced, may collide with
|
||||
equivalent unsynced instances tasks on another device, because the UUIDs are
|
||||
different.
|
||||
- You cannot `wait` a recurring task and have that wait period propagate to
|
||||
all other child tasks.
|
||||
- Task instances cannot individually expire.
|
||||
|
||||
# Proposals
|
||||
|
||||
## Proposal: Eliminate `mask`, `imaѕk` Attributes
|
||||
|
||||
The `mask` attribute in the template is replaced by `last`, which indicates the
|
||||
most recent instance index synthesized. Because instances are never synthesized
|
||||
out of order, we only need to store the most recent index. The `imask` attribute
|
||||
in the instance is no longer needed.
|
||||
|
||||
## Proposal: Rename `parent` to `template`
|
||||
|
||||
The name `parent` implies subtasks, and confuses those who inspect the
|
||||
internals. The value remains the UUID of the template. This frees up the
|
||||
namespace for future use with subtasks.
|
||||
|
||||
## Proposal: New 'rtype' attribute
|
||||
|
||||
To indicate the flavor of recurrence, support the following values:
|
||||
|
||||
* `periodic` - Instances are created on a regular schedule. Example: send birthday flowers. It must occur on a regular schedule, and doesn't matter if you were late last year. This is the default value.
|
||||
* `chained` - Instances are created back to back, so when one instance ends, the next begins, with the same recurrence. Example: mow the lawn. If you mow two days late, the next instance is not two days early to compensate.
|
||||
|
||||
## Proposal: Use relative offsets
|
||||
|
||||
The delta between `wait` and `due` date in the template should be reflected in
|
||||
the delta between `wait` and `due` date in the instance. Similarly,
|
||||
'scheduled' must be handled the same way.
|
||||
|
||||
## Proposal: On load, auto-upgrade legacy tasks
|
||||
|
||||
Upgrade template:
|
||||
|
||||
- Add `rtype:periodic`
|
||||
- Add `last:N` where `N` is the length of `mask`
|
||||
- Delete `mask`
|
||||
|
||||
Upgrade instance:
|
||||
|
||||
- Rename `parent` to `template`
|
||||
- Delete `imask`
|
||||
- Update `wait` if not set to: `wait:due + (template.due - template.wait)`
|
||||
- Update `scheduled` if not set to:
|
||||
`scheduled:due + (template.due - template.scheduled)`
|
||||
|
||||
## Proposal: Deleting a chained instance
|
||||
|
||||
Deleting a `rtype:chained` instance causes the next chained instance to be
|
||||
synthesized. This gives the illusion that the due date is simply pushed out to
|
||||
`(now + template.recur)`.
|
||||
|
||||
## Proposal: Modification Propagation
|
||||
|
||||
TBD
|
||||
|
||||
## Proposal: Exotic Dates
|
||||
|
||||
Expand date specifications to use pattern phrases:
|
||||
|
||||
- `4th thursday in November`
|
||||
- `4th thursday of November`
|
||||
- `Friday before easter`
|
||||
- `next Tuesday`
|
||||
- `last Tuesday`
|
||||
- `last July`
|
||||
- `weekend`
|
||||
- `3 days before eom`
|
||||
- `in the morning`
|
||||
- `4pm`
|
||||
- `noon`
|
||||
- `midnight`
|
||||
|
||||
Got suggestions?
|
||||
|
||||
## Proposal: User-Defined Week Start
|
||||
|
||||
TBD
|
||||
|
||||
# Implementation
|
||||
|
||||
## Implementation: Adding a new `periodic` template
|
||||
|
||||
When adding a new periodic template:
|
||||
|
||||
task add ... due:D recur:R wait:D-1wk scheduled:D-1wk until:U
|
||||
|
||||
Creates:
|
||||
|
||||
template.uuid: NEW_UUID
|
||||
template.description: ...
|
||||
template.entry: now
|
||||
template.modified: now
|
||||
template.due: D
|
||||
template.recur: R (stored in raw form, ie 'P14D')
|
||||
template.wait: D-1wk
|
||||
template.scheduled: D-1wk
|
||||
template.until: U
|
||||
template.rtype: periodic
|
||||
template.last:
|
||||
|
||||
Creating the Nth instance (index N):
|
||||
|
||||
Clone instance from template.
|
||||
|
||||
instance.uuid: NEW_UUID
|
||||
instance.modified: now
|
||||
instance.due: template.due + (N * template.recur)
|
||||
instance.wait: instance.due + (template.due - template.wait)
|
||||
instance.scheduled: instance.due + (template.due - template.scheduled)
|
||||
instance.start:
|
||||
|
||||
template.last: N
|
||||
|
||||
## Implementation: Adding a new `chained` template
|
||||
|
||||
When adding a new chained template:
|
||||
|
||||
task add ... due:D recur:R wait:D-1wk scheduled:D-1wk until:U rtype:chained
|
||||
|
||||
Creates:
|
||||
|
||||
template.uuid: NEW_UUID
|
||||
template.description: ...
|
||||
template.entry: now
|
||||
template.modified: now
|
||||
template.due: D
|
||||
template.recur: R (stored in raw form, ie 'P14D')
|
||||
template.wait: D-1wk
|
||||
template.scheduled: D-1wk
|
||||
template.until: U
|
||||
template.rtype: chained
|
||||
|
||||
Creating the Nth instance (index N):
|
||||
|
||||
Clone instance from template.
|
||||
|
||||
instance.uui d: NEW_UUID
|
||||
instance.mod ified: now
|
||||
instance.due : instance[N-1].end + template.recur
|
||||
instance.wai t: instance.due + (template.due - template.wait)
|
||||
instance.sch eduled: instance.due + (template.due - template.scheduled)
|
||||
instance.sta rt:
|
||||
|
||||
Chained tasks do not obey `rc.recurrence.limit`, and show only one pending task
|
||||
at a time.
|
||||
|
||||
## Implementation: Special handling for months
|
||||
|
||||
Certain recurrence periods are inexact:
|
||||
|
||||
- P1M
|
||||
- P1Y
|
||||
- P1D
|
||||
|
||||
When the recurrence period is `P1M` the number of days in a month varies and
|
||||
causes drift.
|
||||
|
||||
When the recurrence period is `P1Y` the number of days in a year varies and
|
||||
causes drift.
|
||||
|
||||
When the recurrence period is `P1D` the number of hours in a day varies due to
|
||||
daylight savings, and causes drift.
|
||||
|
||||
Drift should be avoided by carefully implementing:
|
||||
|
||||
instance.due: template.due + (N * template.recur)
|
||||
221
docs/rfcs/request.md
Normal file
221
docs/rfcs/request.md
Normal file
|
|
@ -0,0 +1,221 @@
|
|||
---
|
||||
title: "Taskwarrior - Request"
|
||||
---
|
||||
|
||||
|
||||
# Taskserver Message Format
|
||||
|
||||
The Taskserver accepts and emits only messages. These messages look somewhat
|
||||
like email, as defined in [RFC821](https://tools.ietf.org/html/rfc821),
|
||||
[RFC2822](https://tools.ietf.org/html/rfc2822).
|
||||
|
||||
The message format allows for data, metadata, and extensibility. This
|
||||
combination allows the Taskserver to accommodate current and future needs. This
|
||||
document describes the message format, and the supported message types.
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
In this document, we adopt the convention discussed in Section 1.3.2 of
|
||||
[RFC1122](https://tools.ietf.org/html/rfc1122#page-16) of using the capitalized
|
||||
words MUST, REQUIRED, SHOULD, RECOMMENDED, MAY, and OPTIONAL to define the
|
||||
significance of each particular requirement specified in this document.
|
||||
|
||||
In brief: \"MUST\" (or \"REQUIRED\") means that the item is an absolute
|
||||
requirement of the specification; \"SHOULD\" (or \"RECOMMENDED\") means there
|
||||
may exist valid reasons for ignoring this item, but the full implications should
|
||||
be understood before doing so; and \"MAY\" (or \"OPTIONAL\") means that this
|
||||
item is optional, and may be omitted without careful consideration.
|
||||
|
||||
|
||||
## Encoding
|
||||
|
||||
All messages are UTF8-encoded text.
|
||||
|
||||
|
||||
## Message Format
|
||||
|
||||
This format is based on [RFC2822](https://tools.ietf.org/html/rfc2822),
|
||||
\'Internet Message Format\'. Here is an example of the format:
|
||||
|
||||
<SIZE>
|
||||
name: value
|
||||
name2: value2
|
||||
|
||||
payload
|
||||
|
||||
There are three sections. The first is the size, which is a 4-byte, big- Endian,
|
||||
binary byte count of the length of the message, including the 4 bytes for the
|
||||
size.
|
||||
|
||||
The header section is a set of name/value pairs separated by newline characters
|
||||
(U+000D). The name is separated from the value by \': \' (colon U+003A, space
|
||||
U+0020) The header section is terminated by two consecutive newline (U+000D)
|
||||
characters. All text is UTF8-encoded.
|
||||
|
||||
The payload section is arbitrary, and message type-specific. However, it is
|
||||
still UTF8-encoded text.
|
||||
|
||||
|
||||
## Message Requirements
|
||||
|
||||
Messages SHALL contain particular headers. Those are:
|
||||
|
||||
- type
|
||||
- protocol
|
||||
- client
|
||||
|
||||
The \'type\' value is what determines the interpretation of the payload.
|
||||
|
||||
The \'protocol\' value should be \'v1\', or any subsequently published protocol
|
||||
version.
|
||||
|
||||
The \'client\' represent the client identifier, so that any special cases can be
|
||||
handled. For example, an emergency fix that is client version-specific could be
|
||||
released, to support users that have not updated their client, or perhaps the
|
||||
client has not released a fix. The form of the \'version\' value is:
|
||||
|
||||
<product identifier> <version number>
|
||||
|
||||
As an example:
|
||||
|
||||
taskwarrior 2.3.0
|
||||
|
||||
DO NOT spoof any other software using this client value. If another client is
|
||||
spoofed, then patches addressing protocol errors may break working software.
|
||||
|
||||
|
||||
## Auth Data
|
||||
|
||||
Every request from the client SHALL contain \"auth\" information, which involves
|
||||
these header entries:
|
||||
|
||||
org: <organization>
|
||||
user: <user>
|
||||
key: <key>
|
||||
|
||||
The user and org fields uniquely identify a user.
|
||||
|
||||
The key field is generated when a new server account is set up. It is a shared
|
||||
secret, equivalent to a password, and should be protected.
|
||||
|
||||
Authentication failure can result in these errors:
|
||||
|
||||
- 430 Authentication failed
|
||||
- 431 Account suspended
|
||||
|
||||
|
||||
## Status Data
|
||||
|
||||
Every response from the Taskserver SHALL contain status data:
|
||||
|
||||
code: <code>
|
||||
status: <status text>
|
||||
|
||||
The code is a numeric status indicator defined in the [Sync
|
||||
Protocol](/docs/design/protocol).
|
||||
|
||||
|
||||
## Payload Data
|
||||
|
||||
Payload data is optional, arbitrary and message type dependent. It is always
|
||||
UTF8-encoded text.
|
||||
|
||||
|
||||
## Message Types
|
||||
|
||||
The Taskserver supports several message types, thus providing a set of
|
||||
primitives for use by clients.
|
||||
|
||||
It is expected that the number of supported ticket types will increase over
|
||||
time.
|
||||
|
||||
|
||||
## Sync Message
|
||||
|
||||
The \"sync\" message always originates from the client, but the response will
|
||||
contain data from the server. A sync is therefore a single request with a single
|
||||
response.
|
||||
|
||||
The \"sync\" message type MUST contain the following headers:
|
||||
|
||||
- type
|
||||
- org
|
||||
- user
|
||||
- key
|
||||
- client
|
||||
- protocol
|
||||
|
||||
The \"sync\" message payload has this format:
|
||||
|
||||
<uuid>
|
||||
<JSON task 1>
|
||||
<JSON task 2>
|
||||
...
|
||||
<JSON task N>
|
||||
|
||||
Here is an example of a sync message:
|
||||
|
||||
<size>type: sync
|
||||
org: <organization>
|
||||
user: <user>
|
||||
key: <key>
|
||||
client: task 2.3.0
|
||||
protocol: v1
|
||||
|
||||
2e4685f8-34bc-4f9b-b7ed-399388e182e1
|
||||
{"description":"Test data","entry":"20130602T002341Z","status":"pending"}
|
||||
|
||||
The request contains the proper auth section, and the body contains the current
|
||||
sync key followed by a newline characters (U+000D), then a list of
|
||||
JSON-formatted tasks \[2\] each separated by a newline character (U+000D).
|
||||
|
||||
An example response message might be:
|
||||
|
||||
<size>type: response
|
||||
client: taskd 1.0.0
|
||||
protocol: v1
|
||||
code: 200
|
||||
status: Ok
|
||||
|
||||
45da7110-1bcc-4318-d33e-12267a774e0f
|
||||
|
||||
The status indicates success, and the payload contains zero remote task
|
||||
modifications, followed by a sync key.
|
||||
|
||||
|
||||
## Statistics Message
|
||||
|
||||
The message format іs simply:
|
||||
|
||||
<size>type: statistics
|
||||
org: <Organization>
|
||||
user: <User>
|
||||
key: <Key>
|
||||
client: taskd 1.0.0
|
||||
protocol: v1
|
||||
|
||||
There is no payload. An example response message might be:
|
||||
|
||||
<size>type: response
|
||||
client: taskd 1.0.0
|
||||
protocol: v1
|
||||
code: 200
|
||||
status: Ok
|
||||
average request bytes: 0
|
||||
average response bytes: 0
|
||||
average response time: 0.000000
|
||||
errors: 0
|
||||
idle: 1.000000
|
||||
maximum response time: 0.000000
|
||||
total bytes in: 0
|
||||
total bytes out: 0
|
||||
tps: 0.000000
|
||||
transactions: 1
|
||||
uptime: 28
|
||||
|
||||
There is no payload, and the results are in the header variables.
|
||||
|
||||
Note that the statistics gathered by the server are growing, which means new
|
||||
values are occasionally added to the response message. Existing values will not
|
||||
be removed.
|
||||
231
docs/rfcs/rules.md
Normal file
231
docs/rfcs/rules.md
Normal file
|
|
@ -0,0 +1,231 @@
|
|||
---
|
||||
title: "Taskwarrior - Rule System"
|
||||
---
|
||||
|
||||
## Work in Progress
|
||||
|
||||
This design document is a work in progress, and subject to change. Once
|
||||
finalized, the feature will be scheduled for an upcoming release.
|
||||
|
||||
|
||||
# Rule System
|
||||
|
||||
The rule system is a framework that supports highly configurable features, with
|
||||
runtime evaluation, DOM access and an internal API. Implementing a rule system
|
||||
meets the goal of shrinking and stabilizing the product core, while adding new
|
||||
features, and enabling many more.
|
||||
|
||||
|
||||
## Required Enhancements
|
||||
|
||||
To prepare for a Rules System, various subsystems must first be enhanced:
|
||||
|
||||
- DOM references need to be unambiguous, and will all have the `dom.` prefix.
|
||||
|
||||
- DOM references need to be able to access any Taskwarrior data, in any
|
||||
|
||||
- Custom reports will change from referencing `<column>[.<format>]` to simply
|
||||
`<domref>`
|
||||
|
||||
- RC file syntax needs to be enhanced, so support rule definitions, which are
|
||||
multi-line blocks that are indentation-sensitive
|
||||
|
||||
- RC file syntax will support two ways of specifying the same data:
|
||||
|
||||
a.b.c=...
|
||||
|
||||
a:
|
||||
b:
|
||||
c=...
|
||||
|
||||
- RC file syntax will allow the use of environment variables inline:
|
||||
|
||||
name=${TERM}
|
||||
include ${HOME}/.taskrc_local
|
||||
|
||||
- The `Variant` object will migrate to `libshared`
|
||||
|
||||
- The expression evaluator `Eval` object will migrate to `libshared`
|
||||
|
||||
- The column objects will gain a more structured base class, and will serve as
|
||||
providers for DOM references
|
||||
|
||||
- The \'exec\' command will be able to run a rule, if the reference is correct
|
||||
|
||||
- Taskwarrior will store state data in a new `state.data` file
|
||||
|
||||
- `Config` object needs to use the `rat` parser, to tackle the more complex
|
||||
syntax
|
||||
|
||||
- The RC file will support environment variable expansion, where `${NAME}`
|
||||
will be replaced by its corresponding value at launch time
|
||||
|
||||
At that point, the rules system can be implemented in `libshared`, and will use
|
||||
a pluggable architecture to allow its integration into several projects.
|
||||
|
||||
|
||||
## DOM Enhancements
|
||||
|
||||
DOM references will be enhanced, with many more references supported. All DOM
|
||||
references will begin with `dom.`, yielding unambiguous references. References
|
||||
will have a type. Types will support sub-references (`<date>.<month>`,
|
||||
`<tags>.<N>`, `<annotation>.<description>`), and display formats included.
|
||||
|
||||
dom . [<id> .] <attribute> [. <sub-reference>] . <format>
|
||||
|
||||
dom . 123 . entry . year . yyyy
|
||||
dom . 123 . entry
|
||||
dom . 123 . tags
|
||||
dom . 123 . tags . count
|
||||
dom . 123 . tags . 1
|
||||
|
||||
In addition to direct attribute access, DOM references will also support tw
|
||||
references beyond the current set:
|
||||
|
||||
dom.rc.<name>
|
||||
dom.cli.args
|
||||
dom.terminal.width
|
||||
dom.terminal.height
|
||||
dom.system.version
|
||||
dom.system.oѕ
|
||||
|
||||
And will also support higher-level constructs that do not directly correlate to
|
||||
attributes, for example:
|
||||
|
||||
dom.active Boolean indicator of any active tasks
|
||||
dom.synced Boolean indicator of the need to sync
|
||||
dom.rc.path String path of .taskrc file (or override)
|
||||
dom.data.path String path of data directory
|
||||
dom.hooks.path String path of hooks directory
|
||||
|
||||
Finally, access to state:
|
||||
|
||||
dom.state.program
|
||||
dom.state.sync.last
|
||||
dom.state.sync.configured
|
||||
dom.state.run.last
|
||||
dom.state.context
|
||||
|
||||
|
||||
## RC Syntax Changes
|
||||
|
||||
The current configuration system supports only two different forms of syntax:
|
||||
|
||||
<name> = [ <value> ]
|
||||
|
||||
include <file>
|
||||
|
||||
A rule is a new form of syntax that consists of the rule keyword, a name,
|
||||
optional trigger, followed by indented actions in the form of API calls and flow
|
||||
control. For example:
|
||||
|
||||
rule myRule() on_launch:
|
||||
# Some code here
|
||||
|
||||
A rule definition will appear in the RC file, alongside all the existing
|
||||
settings. The rule syntax will require a blank line to terminate the rule
|
||||
definition, the result being that the RC file should be quite readable, although
|
||||
it will look like Python.
|
||||
|
||||
|
||||
## Hook Scripts
|
||||
|
||||
While this functionality can also be implemented using hook scripts, rules will
|
||||
run in-process, and therefore do not require external interpreters to be
|
||||
launched every time. This creates the potential to run faster than a hook
|
||||
script.
|
||||
|
||||
For complex processing, hook scripts will be the preferred mechanism, but as the
|
||||
rules system matures, rules will be made to run more quickly. With adequate
|
||||
performance, a rule will be the preferred implementation over a hook script.
|
||||
This is not expected to be the case at first.
|
||||
|
||||
Hook scripts are not likely to be extended beyond their current form, and with
|
||||
greater DOM access and a growing API, rules should be able to supplant most hook
|
||||
script use cases.
|
||||
|
||||
|
||||
## Rule Triggers
|
||||
|
||||
The set of supported rule types will include:
|
||||
|
||||
* `on_launch` - Triggered on program launch.
|
||||
* `on_add` - Triggered when a task is added. A context task will be provided. The rule can modify the task, and approve or reject it.
|
||||
* `on_modify` - Triggered when a task is modified. A before and after context task will be provided. The rule can modify the task, and approve or reject it.
|
||||
* `on_exit` - Triggered on program exit.
|
||||
* `color` - Triggered when colors are being determined.
|
||||
* `virtual tag` - Defines a new virtual tag.
|
||||
* `format` - Triggered when an attribute needs formatting, defines are new format.
|
||||
|
||||
More rules types will be added for more capabilities in future releases.
|
||||
|
||||
|
||||
## API
|
||||
|
||||
The API is a simple set of actions that may be taken by a rule.
|
||||
|
||||
* `debug(<string>)` - Displays the string in debug mode only and continues processing.
|
||||
* `warn(<string>)` - Displays the string as a warning continues processing.
|
||||
* `error(<string>)` - Displays the string as an error and terminates processing.
|
||||
* `exec(<binary> [ <args> ... ])` - Executes the external program and passes arguments to it. If the program exits with non-zero status, it is treated as an error.
|
||||
* `return <value>` - Provides a result value for the rule, when necessary.
|
||||
|
||||
This is a very limited set at first, and more API calls will be added to support
|
||||
capabilities in future releases.
|
||||
|
||||
|
||||
## Grammar
|
||||
|
||||
The grammar closely tracks that of Python. Blocks are indented consistently.
|
||||
|
||||
* `if <condition>: ... else: ... ` - The condition is a full Algebraic expression, and supports none of the command line conveniences. Terms must be combined with logical operators. The condition is an expression that is evaluated and converted to a Boolean value.
|
||||
* `for <name> in <collection>: ` - There is no native type for a collection, but there are DOM references (`tags` \...) that reference collections. This provides a way to iterate.
|
||||
* `set <name> = <expression> ` - Writes to a named type. The name may be a writable DOM object (`dom...`) or temporary variable storage (`tmp...`). Writing to a read-only DOM reference is an error.
|
||||
* `<function>([<args>]) ` - A function is either a rule or an API call. Calling an undefined function is an error.
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
Here are some example rules which illustrate the syntax and API.
|
||||
|
||||
The replacement for the nag feature:
|
||||
|
||||
rule Nag(before, after) on-modify:
|
||||
if before.urgency < tasks.max.urgency:
|
||||
warn ‘You have more urgent tasks’
|
||||
|
||||
if after.status == 'completed' and before.urgency < (dom.urgency.max - 2.0):
|
||||
warn 'You have more urgent tasks!'
|
||||
|
||||
Correct commonly misspelled word:
|
||||
|
||||
rule CorrectSpelling(task) on_add:
|
||||
set task.description = substitute(task.description, 'teh', 'the')
|
||||
|
||||
Abbreviation expansion:
|
||||
|
||||
rule ExpandAbbreviation(task) on_modify:
|
||||
set task.description = substitute(task.description, '/TW-\d+/', 'https:\/\/github.com\/GothenburgBitFactory\/taskwarrior\/issues\/\1')
|
||||
|
||||
Warn on missing project:
|
||||
|
||||
rule WarnOnMissingProject(task) on_add:
|
||||
if task.project == ‘’:
|
||||
warn(‘Project not specified’)
|
||||
|
||||
Color rule:
|
||||
|
||||
rule ColorizeDue(task) color:
|
||||
if task.due > now:
|
||||
if task.due < (now + 5d):
|
||||
return dom.rc.color.due
|
||||
else:
|
||||
return dom.rc.color.due.later
|
||||
|
||||
Policy:
|
||||
|
||||
rule policyProject(task) on_add:
|
||||
if task.project == '':
|
||||
if rc.default.project == '':
|
||||
error('You must specify a project')
|
||||
set task.project = rc.default.project
|
||||
253
docs/rfcs/sync.md
Normal file
253
docs/rfcs/sync.md
Normal file
|
|
@ -0,0 +1,253 @@
|
|||
---
|
||||
title: "Taskwarrior - Taskserver Sync Algorithm"
|
||||
---
|
||||
|
||||
|
||||
# Taskserver Sync Algorithm
|
||||
|
||||
This document describes how task changes are merged by the Taskserver. It does
|
||||
not describe [the protocol](/docs/design/protocol) used by the Taskserver.
|
||||
|
||||
The Taskserver merges tasks from multiple sources, resulting in conflict- free
|
||||
syncing of data. The algorithm used to achieve this is simple and effective,
|
||||
paralleling what SCM systems do to perform a rebase.
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
In this document, we adopt the convention discussed in Section 1.3.2 of
|
||||
[RFC1122](https://tools.ietf.org/html/rfc1122#page-16) of using the capitalized
|
||||
words MUST, REQUIRED, SHOULD, RECOMMENDED, MAY, and OPTIONAL to define the
|
||||
significance of each particular requirement specified in this document.
|
||||
|
||||
In brief: \"MUST\" (or \"REQUIRED\") means that the item is an absolute
|
||||
requirement of the specification; \"SHOULD\" (or \"RECOMMENDED\") means there
|
||||
may exist valid reasons for ignoring this item, but the full implications should
|
||||
be understood before doing so; and \"MAY\" (or \"OPTIONAL\") means that this
|
||||
item is optional, and may be omitted without careful consideration.
|
||||
|
||||
|
||||
## Problem Definition
|
||||
|
||||
The sync algorithm considers a single task, with multiple changes occurring in
|
||||
two separate locations that must be resolved. The two locations are the local
|
||||
machine and the server. This results in two parallel change sequences.
|
||||
|
||||
Examples using multiple clients collapse down to the simple two-branch case
|
||||
because the clients are merged serially.
|
||||
|
||||
|
||||
## Change Sequence
|
||||
|
||||
A sequence of changes to the same task is represented as:
|
||||
|
||||
T0 --> T1 --> T2
|
||||
|
||||
Although all examples are of the two-branch variety, some involve trivial
|
||||
branches. Going through these examples will illustrate the algorithm. First the
|
||||
legend:
|
||||
|
||||
T0 Represents the original task, the base.
|
||||
T1 Represents the task with a non-trivial set of changes.
|
||||
T2 Represents the task with further changes.
|
||||
|
||||
|
||||
## Deltas
|
||||
|
||||
The transition from T0 \--\> T1 can be seen as a transform applied to T0,
|
||||
resulting in T1. That transform is the delta (d1) between T0 and T1, which is a
|
||||
subtractive term:
|
||||
|
||||
d1 = (T1 - T0)
|
||||
|
||||
Therefore:
|
||||
|
||||
T0 --> T1 = T0 + d1
|
||||
= T0 + (T1 - T0)
|
||||
|
||||
This states that the transition from T0 to T1 is the application of a delta to
|
||||
the original, T0, which results in T1. Applying this to the whole change
|
||||
sequence yields:
|
||||
|
||||
T0 --> T1 --> T2 = T0 + d1 + d2
|
||||
= T0 + (T1 - T0) + (T2 - T1)
|
||||
|
||||
|
||||
## Use Case Classification
|
||||
|
||||
Because clients sync requests are processed serially, there is no need to
|
||||
consider the multiple client cases. This means there is only ever the case with
|
||||
two parallel change sequences = the two branch case.
|
||||
|
||||
|
||||
## Two Branch Case
|
||||
|
||||
The two branch case represents changes made to the same task in two locations,
|
||||
resulting in two deltas that must be applied to the same base.
|
||||
|
||||
T0 --> T1
|
||||
T0 --> T2
|
||||
|
||||
This reduces to a base with two deltas, but the order in which the deltas are
|
||||
applied is important. For example:
|
||||
|
||||
T0 + d1 + d2 =/= T0 + d2 + d1
|
||||
|
||||
The application of deltas is not commutative, except in the trivial case where
|
||||
the two deltas are identical, or the deltas do not overlap. The deltas therefore
|
||||
need to be applied in the correct sequence. Tasks have metadata that indicates
|
||||
the last modified time, which dictates the sequence. Assuming d1 occurred before
|
||||
d2, this neatly collapses down to a single branch sequence:
|
||||
|
||||
T0 + d1 + d2 = T3
|
||||
|
||||
Note that the result in this case is T3, because it will be neither T1 nor T2,
|
||||
unless the deltas are identical.
|
||||
|
||||
|
||||
## Two Branch, Multiple Changes Case
|
||||
|
||||
The two branch case can be complicated by multiple changes per branch:
|
||||
|
||||
T0 --> T1 --> T3 --> T5
|
||||
T0 --> T2 --> T4
|
||||
|
||||
Note that the numbers were chosen to represent the order in which the changes
|
||||
were made. First a list of deltas is generated:
|
||||
|
||||
T0 --> T1 = d1
|
||||
T1 --> T3 = d3
|
||||
T3 --> T5 = d5
|
||||
T0 --> T2 = d2
|
||||
T0 --> T4 = d4
|
||||
|
||||
d1, d3, d5, d2, d4
|
||||
|
||||
Then the deltas are sorted by modified time:
|
||||
|
||||
d1, d2, d3, d4, d5
|
||||
|
||||
Then epplied to the base, yielding T6:
|
||||
|
||||
T0 + d1 + d2 + d3 + d4 +d5 = T6
|
||||
|
||||
|
||||
## Two Branch Case Example
|
||||
|
||||
Suppose the base task looks like this:
|
||||
|
||||
T0 project:ONE due:tomorrow priority:H +tag1 Original description
|
||||
|
||||
The first branch looks like this:
|
||||
|
||||
T1 project:TWO due:23rd priority:H +tag1 Original description
|
||||
|
||||
The second branch looks like this:
|
||||
|
||||
T2 project:ONE due:tomorrow priority:H +tag1 Modified description
|
||||
|
||||
Delta d1 is:
|
||||
|
||||
T0 project:ONE due:tomorrow priority:H +tag1 Original description
|
||||
T1 project:TWO due:23rd priority:H +tag1 Original description
|
||||
----------------------------------------------------------------------
|
||||
d1 project:TWO due:23rd
|
||||
|
||||
Delta d2 is:
|
||||
|
||||
T0 project:ONE due:tomorrow priority:H +tag1 Original description
|
||||
T2 project:ONE due:tomorrow priority:H +tag1 Modified description
|
||||
----------------------------------------------------------------------
|
||||
d2 Modified description
|
||||
|
||||
If d1 occurred before d2, the result is:
|
||||
|
||||
T3 = T0 + d1 + d2
|
||||
= T0 + (project:TWO due:23rd) + (Modified description)
|
||||
|
||||
T3 = project:TWO due:23rd priority:H +tag1 Modified description
|
||||
|
||||
|
||||
## Use Cases
|
||||
|
||||
A range of illustrated use cases, from the trivial to the complex will show the
|
||||
algorithm in use.
|
||||
|
||||
|
||||
## Use Case 1: New Local Task
|
||||
|
||||
Initial state:
|
||||
|
||||
Server: -
|
||||
Client: T0
|
||||
|
||||
The server has no data, and so T0 is stored. The result is now:
|
||||
|
||||
Server: T0
|
||||
Client: T0
|
||||
|
||||
|
||||
## Use Case 2: Local Change
|
||||
|
||||
Initial state:
|
||||
|
||||
Server: T0
|
||||
Client: T0 --> T1
|
||||
|
||||
The server resolves the change:
|
||||
|
||||
T0 --> T1 = T0 + d1
|
||||
= T1
|
||||
|
||||
T1 is stored. The result is now:
|
||||
|
||||
Server: T0 --> T1
|
||||
Client: T1
|
||||
|
||||
|
||||
## Use Case 3: Local and Remote Change
|
||||
|
||||
Initial state:
|
||||
|
||||
Server: T0 --> T1
|
||||
Client: T0 --> T2
|
||||
|
||||
This is the two branch case, and the deltas are generated:
|
||||
|
||||
T0 --> T1 = T0 + d1
|
||||
T0 --> T2 = T0 + d2
|
||||
|
||||
The order of change is determine to be d1, d2, yielding T3:
|
||||
|
||||
T3 = T0 + d1 + d2
|
||||
|
||||
T3 is stored on the server, and returned to the client. The result is now:
|
||||
|
||||
Server: T0 --> T1 --> T2 --> T3
|
||||
Client: T3
|
||||
|
||||
|
||||
## Use Case 4: Multiple Local and Remote Changes
|
||||
|
||||
Initial state:
|
||||
|
||||
Server: T0 --> T1 --> T3
|
||||
Client: T0 --> T2 --> T4
|
||||
|
||||
This is the two branch case, and the deltas are generated:
|
||||
|
||||
T0 --> T1 = T0 + d1
|
||||
T1 --> T3 = T0 + d3
|
||||
T0 --> T2 = T0 + d2
|
||||
T2 --> T4 = T0 + d4
|
||||
|
||||
d1, d3, d2, d4
|
||||
|
||||
The order of change is determine to be d1, d2, d3, d4, yielding T5:
|
||||
|
||||
T5 = T0 + d1 + d2 + d3 + d4
|
||||
|
||||
T5 is stored on the server, and returned to the client. The result is now:
|
||||
|
||||
Server: T0 --> T1 --> T2 --> T3 --> T4 --> T5
|
||||
Client: T5
|
||||
761
docs/rfcs/task.md
Normal file
761
docs/rfcs/task.md
Normal file
|
|
@ -0,0 +1,761 @@
|
|||
---
|
||||
title: "Taskwarrior - Taskwarrior JSON Format"
|
||||
---
|
||||
|
||||
|
||||
# Taskwarrior JSON Format
|
||||
|
||||
When Taskwarrior exchanges data, it uses [JSON](https://www.json.org/). This
|
||||
document describes the structure and semantics for tasks exported from
|
||||
Taskwarrior, imported to Taskwarrior, or synced with the Taskserver.
|
||||
|
||||
Any client of the Taskserver will need to communicate task information. This
|
||||
document describes the format of a single task. It does not describe the
|
||||
communication and sync protocol between client and server.
|
||||
|
||||
This document is subject to change. The data attributes are also subject to
|
||||
change.
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
In this document, we adopt the convention discussed in Section 1.3.2 of
|
||||
[RFC1122](https://tools.ietf.org/html/rfc1122#page-16) of using the capitalized
|
||||
words MUST, REQUIRED, SHOULD, RECOMMENDED, MAY, and OPTIONAL to define the
|
||||
significance of each particular requirement specified in this document.
|
||||
|
||||
In brief: \"MUST\" (or \"REQUIRED\") means that the item is an absolute
|
||||
requirement of the specification; \"SHOULD\" (or \"RECOMMENDED\") means there
|
||||
may exist valid reasons for ignoring this item, but the full implications should
|
||||
be understood before doing so; and \"MAY\" (or \"OPTIONAL\") means that this
|
||||
item is optional, and may be omitted without careful consideration.
|
||||
|
||||
|
||||
## General Format
|
||||
|
||||
The format is JSON, specifically a JSON object as a single line of text,
|
||||
terminated by a newline (U+000D).
|
||||
|
||||
The JSON looks like this:
|
||||
|
||||
{"description":"One two three","status":"pending", ... }
|
||||
|
||||
While this is not a valid task (there are missing fields), the format is
|
||||
illustrated.
|
||||
|
||||
All attribute names are quoted with \" (U+0022). A name will always have a
|
||||
corresponding value, and if a value is blank, then the name/value pair is
|
||||
omitted from the line. Newline characters are not permitted within the value,
|
||||
meaning that a task consists of a single line of text.
|
||||
|
||||
All data is UTF8.
|
||||
|
||||
|
||||
## Data Types
|
||||
|
||||
There are five data types used in the task format.
|
||||
|
||||
|
||||
## Data Type: String
|
||||
|
||||
Strings may consist of any UTF8 encoded characters.
|
||||
|
||||
|
||||
## Data Type: Fixed String
|
||||
|
||||
A fixed string is one value from a set of acceptable values, such as a priority
|
||||
level, where the values may only be \"\", \"L\", \"M\" or \"H\".
|
||||
|
||||
|
||||
## Data Type: UUID
|
||||
|
||||
A UUID is a 32-hex-character lower case string, formatted in this way:
|
||||
|
||||
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
|
||||
|
||||
An example:
|
||||
|
||||
296d835e-8f85-4224-8f36-c612cad1b9f8
|
||||
|
||||
|
||||
## Data Type: Integer
|
||||
|
||||
Integers are rendered in a simple fashion:
|
||||
|
||||
123
|
||||
|
||||
|
||||
## Data Type: Date
|
||||
|
||||
Dates are rendered in ISO 8601 combined date and time in UTC format using the
|
||||
template:
|
||||
|
||||
YYYYMMDDTHHMMSSZ
|
||||
|
||||
An example:
|
||||
|
||||
20120110T231200Z
|
||||
|
||||
No other formats are supported.
|
||||
|
||||
|
||||
## Data Type: Duration
|
||||
|
||||
Duration values represent a time period. They take the form:
|
||||
|
||||
[[<sign>] <number>] <unit>
|
||||
|
||||
Some examples include:
|
||||
|
||||
- -3days
|
||||
- annual
|
||||
- 4hrs
|
||||
|
||||
The supported units are:
|
||||
|
||||
- annual
|
||||
- biannual
|
||||
- bimonthly
|
||||
- biweekly
|
||||
- biyearly
|
||||
- daily
|
||||
- days
|
||||
- day
|
||||
- d
|
||||
- fortnight
|
||||
- hours
|
||||
- hour
|
||||
- hrs
|
||||
- hr
|
||||
- h
|
||||
- minutes
|
||||
- mins
|
||||
- min
|
||||
- monthly
|
||||
- months
|
||||
- month
|
||||
- mnths
|
||||
- mths
|
||||
- mth
|
||||
- mos
|
||||
- mo
|
||||
- quarterly
|
||||
- quarters
|
||||
- qrtrs
|
||||
- qtrs
|
||||
- qtr
|
||||
- q
|
||||
- seconds
|
||||
- secs
|
||||
- sec
|
||||
- s
|
||||
- semiannual
|
||||
- sennight
|
||||
- weekdays
|
||||
- weekly
|
||||
- weeks
|
||||
- week
|
||||
- wks
|
||||
- wk
|
||||
- w
|
||||
- yearly
|
||||
- years
|
||||
- year
|
||||
- yrs
|
||||
- yr
|
||||
- y
|
||||
|
||||
Note that some values lack precision, for example \"2q\" means two quarters, or
|
||||
half a year.
|
||||
|
||||
Note that not all combinations of and make sense, for example \"3annual\" makes
|
||||
no sense, but evaluates to \"3years\".
|
||||
|
||||
|
||||
## The Attributes
|
||||
|
||||
Here are the standard attributes that may comprise a task:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
<th>Type</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>status</td>
|
||||
<td>String</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>uuid</td>
|
||||
<td>UUID</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>entry</td>
|
||||
<td>Date</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>description</td>
|
||||
<td>String</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>start</td>
|
||||
<td>Date</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>end</td>
|
||||
<td>Date</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>due</td>
|
||||
<td>Date</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>until</td>
|
||||
<td>Date</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>wait</td>
|
||||
<td>Date</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>modified</td>
|
||||
<td>Date</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>scheduled</td>
|
||||
<td>Date</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>recur</td>
|
||||
<td>String</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>mask</td>
|
||||
<td>String</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>imask</td>
|
||||
<td>Integer</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>parent</td>
|
||||
<td>UUID</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>project</td>
|
||||
<td>String</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>priority</td>
|
||||
<td>String</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>depends</td>
|
||||
<td>String</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>tags *</td>
|
||||
<td>String</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>annotation *</td>
|
||||
<td>String</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>(UDA)</td>
|
||||
<td>?</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
\* Both tags and annotations are lists of strings and objects.
|
||||
|
||||
Any UDA fields are assumed to be of type string.
|
||||
|
||||
There are other forms, which are conditional upon the state of a task:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Status Value</th>
|
||||
<th>Pending</th>
|
||||
<th>Deleted</th>
|
||||
<th>Completed</th>
|
||||
<th>Waiting</th>
|
||||
<th>Recurring Parent</th>
|
||||
<th>Recurring Child</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>status</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>uuid</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>entry</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>description</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>start</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>end</td>
|
||||
<td></td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>due</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td>Opt</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>until</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>scheduled</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>wait</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>recur</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td class="danger">Reqd</td>
|
||||
<td class="danger">Reqd</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>mask</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td class="info">Intrn</td>
|
||||
<td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>imask</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td class="info">Intrn</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>parent</td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td class="danger">Reqd</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>annotation</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>project</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>tags</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>priority</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>depends</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>modified</td>
|
||||
<td class="info">Intrn</td>
|
||||
<td class="info">Intrn</td>
|
||||
<td class="info">Intrn</td>
|
||||
<td class="info">Intrn</td>
|
||||
<td class="info">Intrn</td>
|
||||
<td class="info">Intrn</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>UDA</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
<td>Opt</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
(Legend: Reqd = required, Opt = optional, Intrn = Internally generated)
|
||||
|
||||
All tasks have four required fields. There are other states in which a task may
|
||||
exist, and the requirements change. At a minimum, a valid task contains:
|
||||
|
||||
- uuid
|
||||
- status
|
||||
- entry
|
||||
- description
|
||||
|
||||
*Deleted*\
|
||||
A deleted task MUST also have \"status\":\"deleted\", an \"end\" date and a
|
||||
\"modified\" date.
|
||||
|
||||
*Completed*\
|
||||
A completed task MUST also have \"status\":\"completed\", an \"end\" date and a
|
||||
\"modified\" date.
|
||||
|
||||
*Waiting*\
|
||||
A waiting task MUST also have \"status\":\"waiting\" and a \"wait\" date. The
|
||||
task is hidden from the user, until that \"wait\" date has passed, whereupon the
|
||||
status reverts to \"pending\", and the \"wait\" date is removed.
|
||||
|
||||
*Recurring Parent*\
|
||||
When a recurring task is entered, it MUST have \"status\":\"recurring\", a
|
||||
\"recur\" period and a \"due\" date. It MAY also have an \"until\" date.
|
||||
Recurring parent tasks are hidden from the user.
|
||||
|
||||
*Recurring Child*\
|
||||
A recurring child task is not created by the user, but is cloned from the
|
||||
recurring parent task by the Taskserver. It may be modified by the user. On
|
||||
completion, there is special handling to be done. See section 3.11.
|
||||
|
||||
|
||||
## Additional Attributes
|
||||
|
||||
There MAY be other fields than those listed above in a task definition. Such
|
||||
fields MUST be preserved intact by any client, which means that if a task is
|
||||
downloaded that contains an unrecognized field, that field MUST not be modified,
|
||||
and MUST continue to exist in the task..
|
||||
|
||||
User Defined Attributes (UDAs) are additional fields.
|
||||
|
||||
|
||||
## Attribute Details
|
||||
|
||||
The individual fields convey important information about a task, and in some
|
||||
cases work only in collusion with other fields. All such details are listed
|
||||
here.
|
||||
|
||||
|
||||
## Attribute: status
|
||||
|
||||
The status field describes the state of the task, which may ONLY be one of these
|
||||
literal strings:
|
||||
|
||||
"status":"pending"
|
||||
"status":"deleted"
|
||||
"status":"completed"
|
||||
"status":"waiting"
|
||||
"status":"recurring"
|
||||
|
||||
A pending task is a task that has not yet been completed or deleted. This is the
|
||||
typical state for a task.
|
||||
|
||||
A deleted task is one that has been removed from the pending state, and MUST
|
||||
have an \"end\" field specified. Given the required \"entry\" and \"end\" field,
|
||||
it can be determined how long the task was pending.
|
||||
|
||||
A completed task is one that has been removed from the pending state by
|
||||
completion, and MUST have an \"end\" field specified. Given the required
|
||||
\"entry\" and \"end\" fields, it can be determine how long the task was pending.
|
||||
|
||||
A waiting task is ostensibly a pending task that has been hidden from typical
|
||||
view, and MUST have a \"wait\" field containing the date when the task is
|
||||
automatically returned to the pending state. If a client sees a task that is in
|
||||
the waiting state, and the \"wait\" field is earlier than the current date and
|
||||
time, the client MUST remove the \"wait\" field and set the \"status\" field to
|
||||
\"pending\".
|
||||
|
||||
A recurring task is essentially a parent template task from which child tasks
|
||||
are cloned. The parent remains hidden from view, and contains a \"mask\" field
|
||||
that represents the recurrences. Each cloned child task has an \"imask\" field
|
||||
that indexes into the parent \"mask\" field, as well as a \"parent\" field that
|
||||
lists the UUID of the parent.
|
||||
|
||||
|
||||
## Attribute: uuid
|
||||
|
||||
When a task is created, it MUST be assigned a new UUID by the client. Once
|
||||
assigned, a UUID field MUST NOT be modified. UUID fields are permanent.
|
||||
|
||||
|
||||
## Attribute: entry
|
||||
|
||||
When a task is created, it MUST be assigned an \"entry\" date by the client.
|
||||
This is the creation date of the task.
|
||||
|
||||
|
||||
## Attribute: description
|
||||
|
||||
When a task is created, it MUST have a \"description\" field value, which
|
||||
contains UTF8 characters. A \"description\" field may not contain newline
|
||||
characters, but may contain other characters, properly escaped. See
|
||||
<https://json.org> for details.
|
||||
|
||||
|
||||
## Attribute: start
|
||||
|
||||
To indicate that a task is being worked on, it MAY be assigned a \"start\"
|
||||
field. Such a task is then considered Active.
|
||||
|
||||
|
||||
## Attribute: end
|
||||
|
||||
When a task is deleted or completed, is MUST be assigned an \"end\" field. It is
|
||||
not valid for a task to have an \"end\" field unless the status is also
|
||||
\"completed\" or \"deleted\". If a completed task is restored to the \"pending\"
|
||||
state, the \"end\" field is removed.
|
||||
|
||||
|
||||
## Attribute: due
|
||||
|
||||
A task MAY have a \"due\" field, which indicates when the task should be
|
||||
completed.
|
||||
|
||||
|
||||
## Attribute: until
|
||||
|
||||
A recurring task MAY have an \"until\" field, which is the date after which no
|
||||
more recurring tasks should be generated. At that time, the parent recurring
|
||||
task is set to \"completed\".
|
||||
|
||||
|
||||
## Attribute: wait
|
||||
|
||||
A task MAY have a \"wait\" field date, in conjunction with a \"status\" of
|
||||
\"waiting\". A waiting task is one that is not typically shown on reports until
|
||||
it is past the wait date.
|
||||
|
||||
An example of this is a birthday reminder. A task may be entered for a birthday
|
||||
reminder in 10 months time, but can have a \"wait\" date 9 months from now,
|
||||
which means the task remains hidden until 1 month before the due date. This
|
||||
prevents long-term tasks from cluttering reports until they become relevant.
|
||||
|
||||
|
||||
## Attribute: recur
|
||||
|
||||
The \"recur\" field is for recurring tasks, and specifies the period between
|
||||
child tasks, in the form of a duration value. The value is kept in the raw state
|
||||
(such as \"3wks\") as a string, so that it may be evaluated each time it is
|
||||
needed.
|
||||
|
||||
|
||||
## Attribute: mask
|
||||
|
||||
A parent recurring task has a \"mask\" field that is an array of child status
|
||||
indicators. Suppose a task is created that is due every week for a month. The
|
||||
\"mask\" field will look like:
|
||||
|
||||
"----"
|
||||
|
||||
This mask has four slots, indicating that there are four child tasks, and each
|
||||
slot indicates, in this case, that the child tasks are pending (\"-\"). The
|
||||
possible slot indicators are:
|
||||
|
||||
* `-` - Pending
|
||||
* `+` - Completed
|
||||
* `X` - Deleted
|
||||
* `W` - Waiting
|
||||
|
||||
Suppose the first three tasks has been completed, the mask would look like this:
|
||||
|
||||
"+++-"
|
||||
|
||||
If there were only three indicators in the mask:
|
||||
|
||||
"+-+"
|
||||
|
||||
This would indicate that the second task is pending, the first and third are
|
||||
complete, and the fourth has not yet been generated.
|
||||
|
||||
|
||||
## Attribute: imask
|
||||
|
||||
Child recurring tasks have an \"imask\" field instead of a \"mask\" field like
|
||||
their parent. The \"imask\" field is a zero-based integer offset into the
|
||||
\"mask\" field of the parent.
|
||||
|
||||
If a child task is completed, one of the changes that MUST occur is to look up
|
||||
the parent task, and using \"imask\" set the \"mask\" of the parent to the
|
||||
correct indicator. This prevents recurring tasks from being generated twice.
|
||||
|
||||
|
||||
## Attribute: parent
|
||||
|
||||
A recurring task instance MUST have a \"parent\" field, which is the UUID of the
|
||||
task that has \"status\" of \"recurring\". This linkage between tasks,
|
||||
established using \"parent\", \"mask\" and \"imask\" is used to track the need
|
||||
to generate more recurring tasks.
|
||||
|
||||
|
||||
## Attribute: annotation\_\...
|
||||
|
||||
Annotations are strings with timestamps. Each annotation itself has an \"entry\"
|
||||
field and a \"description\" field, similar to the task itself. Annotations form
|
||||
an array named \"annotations\". For example (lines broken for clarity):
|
||||
|
||||
"annotations":[
|
||||
{"entry":"20120110T234212Z","description":"Remember to get the mail"},
|
||||
{"entry":"20120110T234559Z","description":"Pay the bills"}
|
||||
]
|
||||
|
||||
|
||||
## Attribute: project
|
||||
|
||||
A project is a single string. For example:
|
||||
|
||||
"project":"Personal Taxes"
|
||||
|
||||
Note that projects receive special handling, so that when a \".\" (U+002E) is
|
||||
used, it implies a hierarchy, which means the following two projects:
|
||||
|
||||
"Home.Kitchen"
|
||||
"Home.Garden"
|
||||
|
||||
are both considered part of the \"Home\" project.
|
||||
|
||||
|
||||
## Attribute: tags
|
||||
|
||||
The \"tags\" field is an array of string, where each string is a single word
|
||||
containing no spaces. For example:
|
||||
|
||||
"tags":["home","garden"]
|
||||
|
||||
|
||||
## Attribute: priority
|
||||
|
||||
The \"priority\" field, if present, MAY contain one of the following strings:
|
||||
|
||||
"priority":"H"
|
||||
"priority":"M"
|
||||
"priority":"L"
|
||||
|
||||
These represent High, Medium and Low priorities. An absent priority field
|
||||
indicates no priority.
|
||||
|
||||
|
||||
## Attribute: depends
|
||||
|
||||
The \"depends\" field is a string containing a comma-separated unique set of
|
||||
UUIDs. If task 2 depends on task 1, then it is task 1 that must be completed
|
||||
first. Task 1 is considered a \"blocking\" tasks, and task 2 is considered a
|
||||
\"blocked\" task. For example:
|
||||
|
||||
"depends":",, ..."
|
||||
|
||||
Note that in a future version of this specification, this will be changed to a
|
||||
JSON array of strings, like the \"tags\" field.
|
||||
|
||||
|
||||
## Attribute: modified
|
||||
|
||||
A task MUST have a \"modified\" field set if it is modified. This field is of
|
||||
type \"date\", and is used as a reference when merging tasks.
|
||||
|
||||
|
||||
## Attribute: scheduled
|
||||
|
||||
A task MAY have a \"scheduled\" field, which indicates when the task should be
|
||||
available to start. A task that has passed its \"scheduled\" data is said to be
|
||||
\"ready\".
|
||||
|
||||
|
||||
## User Defined Attributes
|
||||
|
||||
A User Defined Attribute (UDA) is a field that is defined via configuration.
|
||||
Given that the configuration is not present in the JSON format of a task, any
|
||||
fields that are not recognized are to be treated as UDAs. This means that if a
|
||||
task contains a UDA, unless the meaning of it is understood, it MUST be
|
||||
preserved.
|
||||
|
||||
UDAs may have one of four types: string, numeric, date and duration.
|
||||
|
||||
BIN
docs/rfcs/week.png
Normal file
BIN
docs/rfcs/week.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
35
docs/rfcs/workweek.md
Normal file
35
docs/rfcs/workweek.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
---
|
||||
title: "Taskwarrior - Work Week Support"
|
||||
---
|
||||
|
||||
## Work in Progress
|
||||
|
||||
This design document is a work in progress, and subject to change. Once
|
||||
finalized, the feature will be scheduled for an upcoming release.
|
||||
|
||||
|
||||
# Work Week Support
|
||||
|
||||
Taskwarrior supports the idea that a week starts on either a Sunday or a Monday,
|
||||
as determined by configuration. This was added eight years ago, simply for
|
||||
display purposes in the `calendar` report. Since then its use has propagated and
|
||||
it influences the `sow` date reference.0
|
||||
|
||||
Further requests have been made to make this more flexible, so that the notion
|
||||
of \'weekend\' can be defined. Furthermore, the idea that every week has a
|
||||
weekend has also been questioned.
|
||||
|
||||
It has become clear that a `weekstart` setting, and the notion of a weekend are
|
||||
no longer useful.
|
||||
|
||||
|
||||
## Proposed Support
|
||||
|
||||
One option is to allow the user to completely define a work week in the
|
||||
following way:
|
||||
|
||||
workweek=1,2,3,4,5
|
||||
|
||||
With Sunday as day zero, this states that the work week is the typical Monday -
|
||||
Friday. From this setting, the meaning of `soww` and `eoww` can be determined,
|
||||
as well as `recur:weekday`.
|
||||
BIN
docs/rfcs/year.png
Normal file
BIN
docs/rfcs/year.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
Loading…
Add table
Add a link
Reference in a new issue