mirrors/takentaal
3
0
Fork 0
mirror of https://codeberg.org/NLnet/takentaal.git synced 2025-08-29 14:00:06 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Some fixes to the spec text and update to 1.0

Browse source 
Note that 1.0 is not final until it has been tagged in git.
This commit is contained in:
Jos van den Oever 2024-09-04 17:05:39 +02:00
parent 1decf93f56
commit 3bf56e0345
1 changed files with 23 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

42
takentaal.spec.0.1.0.md → takentaal.spec.1.0.md
View file

@ -1,6 +1,6 @@
# TakenTaal Spec
Version 0.1.0
Version 1.0
## Abstract
@ -13,7 +13,7 @@ and validated using automated tooling.
A TakenTaal document looks as follows:
```
takentaal v0.1.0
takentaal v1.0
# {10000} Project Name
@ -128,13 +128,15 @@ the original document.
In short, documents are formatted as follows:
- the first line is "takentaal v0.1.0"
- the first line is "takentaal v1.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,
- lines beginning with "- " are a subtask,
- in amendments, lines beginning with "/ ", "* " or "! " are subtasks with
a special status,
- all other lines are the description of the plan or a task.
Titles MAY contain an amount.
Titles MAY be preceded by an amount in curly brackets.
Descriptions consists of paragraphs, each paragraph corresponding to a single
line of text.
@ -150,11 +152,11 @@ newline characters.
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".
version to be "1.0".
The header is formatted as follows:
header = "takentaal v0.1.0"
header = "takentaal v1.0"
### 4.3 Title
@ -193,7 +195,7 @@ itself.
A line that gives the plan a title MUST be formatted as follows:
plan-title = "#" *SP [amount] *SP title
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.
@ -209,7 +211,7 @@ document.
A line that declares a task's title is formatted as follows:
task-title = "##" *SP [amount] *SP title
task-title = "## " *SP [amount] *SP title
A line that declares a subtask is formatted as follows:
@ -222,10 +224,12 @@ subtask status is formatted as follows:
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
- "- ": the subtask is considered new
- "/ ": the subtask is considered partially completed
- "* ": the subtask is considered fully completed
- "! ": the subtask is considered cancelled
with the last three being only available in amendments.
Every non-empty line that does not follow the formats mentioned above is
considered a paragraph of the description of the task.
@ -275,8 +279,8 @@ 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.
Imagine a scenario where one of the subtasks was already (partially) 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
@ -320,7 +324,7 @@ invalid, to clearly communicate what rules are followed by the implementation.
Example 1: a minimal TakenTaal document:
```
takentaal v0.1.0
takentaal v1.0
# Project Name
This is the description of the entire work plan.
@ -343,7 +347,7 @@ This is the description of the second task.
Example 2: a full valid TakenTaal document:
```
takentaal v0.1.0
takentaal v1.0
# {3000} Project Name
This is the description of the entire work plan.
@ -369,7 +373,7 @@ This is the description of the second task.
Example 3: a document with status indicators:
```
takentaal v0.1.0
takentaal-amendment v1.0
# Project Name
## {500} First task
@ -385,7 +389,7 @@ takentaal v0.1.0
Example 4: a document that gets flagged during auditing (amounts mismatch):
```
takentaal v0.1.0
takentaal v1.0
# Project Name
## First task {2000 EUR}