Add TakenTaal 0.1.0 spec

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
+```

takentaal.spec.latest.md

@@ -0,0 +1 @@
+takentaal.spec.0.1.0.md