diff --git a/takentaal.spec.0.1.0.md b/takentaal.spec.0.1.0.md new file mode 100644 index 0000000..6da91fd --- /dev/null +++ b/takentaal.spec.0.1.0.md @@ -0,0 +1,395 @@ +# TakenTaal Spec + +Version 0.1.0 + +## Abstract + +TakenTaal is a plain text format for writing plans that describe work that is to +be performed within the context of a grant. It is designed to be the document +that is written by recipients of a grant and sent to the reviewers of that +grant. The syntax allows these documents to be parsed by machines and audited +and validated using automated tooling. + +A TakenTaal document looks as follows: + +``` +takentaal v0.1.0 + +# {10000} Project Name + +This is the description of the entire work plan. + +## {1000} First task + +This is the description of the first task. + +- {500} First subtask +- {500} Second subtask + +## {2000} Second task + +This is the description of the second task. + +- { 750} First subtask +- {1250} Second subtask +``` + +## 1. Introduction + +The specification was written by the NLnet Foundation to facilitate the +communication of intended work between them and their grantees. + +TakenTaal is a Dutch closed compound word translating in English to "language of +tasks". + +The specification was written with several goals in mind: + +- TakenTaal documents should describe and divide work in tasks and subtasks, +- TakenTaal documents should be flat, concise and unambiguous, +- TakenTaal documents should be auditable, +- TakenTaal documents should be diffable, +- TakenTaal documents should be lockable, +- TakenTaal documents should be amendable. + +Definitions for some of these requirements are provided in the Definitions +section. + +This specification will offer suggestions on how to process the documents and +what to do with the results of the processing, but ultimately it is up to the +implementation to decide on the processing rules. For example, implementations +could allow under- and/or overbudgeting, in which case an audit of such a +document should merely result in a warning, not a rejection. + +It is important to note that these documents are not designed for automated +reviewing, they are designed to be reviewed by humans and to be parsed by tools +that will assist in the reviewing process. + +## 2. Conventions + +The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, +“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be +interpreted as described in RFC2119. + +This specification uses the Augmented Backus-Naur Form (ABNF) notation of +RFC2234. The following definitions are also used in this document: + +character: A valid Unicode character + +ucalpha: Uppercase alphabetical characters (A-Z) + +## 3. Definitions + +A title is a sequence of characters on a single line. It SHOULD provide a clear +and concise summary of the data structure it belongs to. + +A description is a sequence of characters that MAY be divided in multiple lines. +It SHOULD provide more details and context to the data structure it belongs to. + +An amount is an integer and represents a monetary value. It SHOULD provide a +financial context to the data structure it belongs to. + +A work plan is a data structure that consists of the following elements: + +- a title, +- a description, +- an expected amount (optional), +- a set of tasks. + +A task is a data structure that consists of the following elements: + +- a title, +- a description, +- an expected amount (optional), +- a set of subtasks. + +A subtask is a data structure that consists of the following elements: + +- a title, +- an amount. + +Auditing a TakenTaal document refers to the process of parsing the document and +comparing and validating the amounts against the expected amounts of the plan, +the tasks and the subtasks. + +Diffing a TakenTaal document refers to the process of providing feedback to the +reader of the document on the exact changes that ocurred between copies of the +same document. + +Locking a TakenTaal document (partially) refers to the process of marking parts +of the document with special flags that will disallow any modification to said +parts when amending the document. + +Amending a TakenTaal document refers to the process of taking a fixed version of +the document, making a copy of that document, editing the copy, and receiving +feedback from the parser whether the edits are allowed to be merged back into +the original document. + +## 4. Document syntax + +In short, documents are formatted as follows: + +- the first line is "takentaal v0.1.0" +- lines beginning with "# " are the title of the plan, +- lines beginning with "## " are the title of a task, +- lines beginning with "- ", "/ ", "* " or "! " are a subtask, +- all other lines are the description of the plan or a task. + +Titles MAY contain an amount. + +Descriptions consists of paragraphs, each paragraph corresponding to a single +line of text. + +### 4.1 Characters and lines + +TakenTaal documents are sequences of valid Unicode characters. + +TakenTaal documents are parsed line for line, where lines are separated by +newline characters. + +### 4.2 Header + +TakenTaal documents MUST begin with a header line announcing the version of the +TakenTaal spec used. The TakenTaal spec you are currently reading expects the +version to be "0.1.0". + +The header is formatted as follows: + + header = "takentaal v0.1.0" + +### 4.3 Title + +TakenTaal documents MUST contain a plan title and MAY contain task titles and +subtask titles. + +A title is formatted as follows: + + title = character *(character / SP) + +### 4.4 Description + +TakenTaal documents MAY contain description lines for plans or tasks. + +A description line is formatted as follows: + + description = character *(character / SP) + +Two description lines interrupted by a newline MUST be separated into two +paragraphs. + +### 4.5 Amount + +TakenTaal documents MAY contain financial amounts. Amount MAY contain spaces, +useful to align them for visual clarity. + +A financial amount is formatted as follows: + + amount = "{" *SP 1*DIGIT *SP "}" + +### 4.6 Plan + +A TakenTaal document, in its entirety, represents a plan. All lines of the +document that are placed above the first task declaration describe the plan +itself. + +A line that gives the plan a title MUST be formatted as follows: + + plan-title = "#" *SP [amount] *SP title + +A TakenTaal document MUST have one title. Subsequent lines formated as the +plan-title MUST be added to the description of the plan. + +Every line that does not follow the format mentioned above is considered part of +the description of the plan. + +### 4.7 Task + +A task MUST always begin with the declaration of its title. The definition of +the task ends either with the declaration of a new task, or the end of the +document. + +A line that declares a task's title is formatted as follows: + + task-title = "##" *SP [amount] *SP title + +A line that declares a subtask is formatted as follows: + + subtask = subtask-status *SP [amount] *SP title + +Every subtask has its status encoded in the first character of the line. The +subtask status is formatted as follows: + + subtask-status = "-" / "/" / "*" / "!" + +The subtask status characters have the following meaning: + +- "-": the subtask is considered new +- "/": the subtask is considered partially completed +- "*": the subtask is considered fully completed +- "!": the subtask is considered cancelled + +Every non-empty line that does not follow the formats mentioned above is +considered a paragraph of the description of the task. + +## 5. Document processing + +### 5.1 Auditing + +The goal of auditing a TakenTaal document is to match the amounts of the plan, +the tasks and the subtasks. By default, the plan amount SHOULD be equal to the +sum of the task amounts. The task amount SHOULD be equal to the sum of the +subtask amounts. + +If amounts do not match, it is up to the implementation to decide whether to +entirely reject the plan, or simply warn the reviewer. + +Cancelled subtasks MUST NOT be considered during auditing. + +### 5.2 Diffing + +The goal of diffing a TakenTaal document with an older version of itself is to +compare the changes between the two versions and observe what was changed. This +process is usually applied when amending a document. This is helpful for both +the writers and the reviewers of the document, to clearly understand what an +amendment exactly changes to a document. + +Because these documents are plain text, most plain text diff tools and +algorithms should work. + +### 5.3 Amending + +A TakenTaal document amendment communicates the intent to change parts of the +work plan. This includes changing titles and/or description, changing an item's +associated amount, and/or adding/removing tasks/subtasks. + +An amendment is an entire TakenTaal document, usually a copy of the original +document, which was then modified. Amendments can be plain text diffed against +the original document to observe what changes are introduced by the amendment. + +Updating a subtask status SHOULD be done by the reviewers in their copy of the +document. If so, amendments SHOULD NOT be used to update a subtask status. + +### 5.4 Validating an amendment + +To assist with reviewing the amendments and avoid modifications that may +invalidate the documents, TakenTaal documents can be partially locked using +status indicators. These indicators are machine-parsable to allow for automated +validation. + +Imagine a scenario where one of the subtasks was already completed and paid out. +Amendments MUST be disallowed to modify that subtask. + +This is where locking a subtask comes in. Subtasks can be locked by using any +status indicator other than "-" (see 4.7). When locked, a subtask MUST not be +allowed to receive modifications in the following properties: + +- title, +- amount, +- index (optional). + +The index is the position of the subtask in the work plan: a subtask with index +"3.2" is the second subtask of the third task, in the order that they appear in +the TakenTaal document. Implementations are RECOMMENDED to lock this index as +well. To keep the index locked, subtasks MUST NOT be added or removed above the +locked subtask. Instead of removing a subtask, they can be marked as cancelled +with the "!" status character, hiding them from document audits while +maintaining their index and the indexes of subtasks after it. It is RECOMMENDED +to always put added subtasks after existing subtasks. + +Tasks SHOULD be locked by default and SHOULD be cancelled by cancelling all +their subtasks. Tasks SHOULD NOT be allowed to be edited or removed. It is +RECOMMENDED to add a new task at the end of the document instead. + +The original document MUST be stored by the reviewing party and MUST be used to +validate the incoming amendment for amendment validation to be reliable. The +document editors supply the amendment, but the reviewers MUST validate the +incoming amendment against their own version of the original document. + +The status indicators in the original document SHOULD take precedence over the +ones in the amendment. For example, a subtask that is locked in the original +document SHOULD NOT be unlocked by an amendment. + +Implementations decide what types of status indicator update to allow. For +example, they COULD allow amendments to mark a subtask as cancelled but disallow +amendments to mark a subtask as completed. + +Implementations SHOULD provide detailed feedback about why an amendment is +invalid, to clearly communicate what rules are followed by the implementation. + +## 6. Examples + +Example 1: a minimal TakenTaal document: + +``` +takentaal v0.1.0 +# Project Name + +This is the description of the entire work plan. + +## First task + +This is the description of the first task. + +- {500} First subtask +- {500} Second subtask + +## Second task + +This is the description of the second task. + +- { 500} First subtask +- {1500} Second subtask +``` + +Example 2: a full valid TakenTaal document: + +``` +takentaal v0.1.0 +# {3000} Project Name + +This is the description of the entire work plan. + +## {1000} First task + +This is the description of the first task. +This line is still part of the first paragraph of the description. + +This is a second paragraph of that description. + +- {500} First subtask +- {500} Second subtask + +## {2000} Second task + +This is the description of the second task. + +- { 500} First subtask +- {1500} Second subtask +``` + +Example 3: a document with status indicators: + +``` +takentaal v0.1.0 +# Project Name + +## {500} First task + +! {500} This subtask has been cancelled +* {500} This subtask has been completed + +## {500} Second task + +/ {500} This subtask was partially completed +``` + +Example 4: a document that gets flagged during auditing (amounts mismatch): + +``` +takentaal v0.1.0 +# Project Name + +## First task {2000 EUR} + +- {500} First subtask +- {500} Second subtask +``` diff --git a/takentaal.spec.latest.md b/takentaal.spec.latest.md new file mode 120000 index 0000000..42a713d --- /dev/null +++ b/takentaal.spec.latest.md @@ -0,0 +1 @@ +takentaal.spec.0.1.0.md \ No newline at end of file