From 494c7fc2d7d882a8a456560c0c9319894ab1ef20 Mon Sep 17 00:00:00 2001 From: ansgarz Date: Tue, 19 Apr 2022 17:35:26 +0200 Subject: [PATCH] update doc --- doc/ForDevelopers.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/doc/ForDevelopers.md b/doc/ForDevelopers.md index 07223c7..9e5a367 100644 --- a/doc/ForDevelopers.md +++ b/doc/ForDevelopers.md @@ -1,15 +1,34 @@ # Information for developers -## Build a provs jar-file yourself +## Create a provs jar-file * Clone this repo * Build the jar-file by `./gradlew uberjarDesktop` -* In folder build/libs you'll find the file `provs.jar` +* In folder build/libs you'll find the file `provs-desktop.jar` -The fatjar is a Java jar-file incl. all required dependencies. +This uberjar is a Java jar-file including all required dependencies. -### Sequence diagram +## Call hierarchy Find below an example of a sequence diagram when provisioning a desktop workplace: -![img.png](resources/provision-workplace-sequence.diagram.png) \ No newline at end of file +![img.png](resources/provision-workplace-sequence.diagram.png) + + +## Task + +```kotlin +fun Prov.provisionK8s() = task { /* ... code and subtasks come here ... */ } +``` + +Very often you'll see a task definition like this in provs and might wonder ... + +### What is a task ? + +A task is the **basic execution unit** in provs. When executed, each task produces exactly one result (line) with either success or failure. + +The success or failure is computed automatically in the following way: +* a **task** fails if it calls subtasks and if at least one subtask has failed +* a **taskWithResult** works the same except that it requires an additional result to be returned which is also included in the success calculation +* a task defined with **optional** (i.e. `= optional { /* ... */ }` always returns success (even if there are failing subtasks) +* **requireLast** defines a task which must provide an explicit result and solely this result counts for success calculation