From 2b67e97cecdf74650ff4bf6fa6e6b8e8a477fb1c Mon Sep 17 00:00:00 2001
From: Gerhard Lazu <gerhard@lazu.co.uk>
Date: Wed, 9 Mar 2022 18:10:52 +0000
Subject: [PATCH] Europa docs plan updates after Client API & dagger do

Follow-up to https://github.com/dagger/dagger/pull/1683

Part of https://github.com/dagger/dagger/issues/1327

Signed-off-by: Gerhard Lazu <gerhard@lazu.co.uk>
---
 docs/core-concepts/1202-plan.md | 68 +++++++++++++++++++++------------
 1 file changed, 44 insertions(+), 24 deletions(-)

diff --git a/docs/core-concepts/1202-plan.md b/docs/core-concepts/1202-plan.md
index 8e22fc7a..43fda49b 100644
--- a/docs/core-concepts/1202-plan.md
+++ b/docs/core-concepts/1202-plan.md
@@ -7,62 +7,80 @@ displayed_sidebar: europa
 
 A CI/CD pipeline declared in Dagger starts with a plan, specifically `dagger.#Plan`
 
-This plan is the entrypoint for everything that runs within a pipeline.
+This plan is the entrypoint for everything that runs within a pipeline. The simplest plan will usually:
+
+- interact with the client filesystem to read (e.g. source code) or write files (e.g. build output)
+- read environment variables
+- declare a few actions, e.g. deps, test & build
 
-The simplest plan will have at least one input - the source code - and a few actions, usually build, test & deploy.
 This is our **Getting Started** example app plan structure:
 
 ```cue
 dagger.#Plan & {
-  inputs: {
-    directories: app: path: "./"
-    // ...
+  client: {
+    filesystem: {
+      // ...
+    }
+    env: {
+      // ...
+    }
   }
   actions: {
-    build: yarn.#Build & {
+    deps: docker.#Build & {
       // ...
     }
-    test: yarn.#Run & {
+    test: bash.#Run & {
       // ...
     }
-    // ...
+    build: {
+      run: bash.#Run & {
+         // ...
+      }
+      contents: dagger.#Subdir & {
+        // ...
+      }
+    }
   }
 }
 ```
 
-When the above plan gets executed via `dagger up`, it produces the following output:
+When the above plan gets executed via `dagger do build`, it produces the following output:
 
 ```shell
-dagger up dev.cue
-[✔] inputs.directories.app                                        0.1s
-[✔] actions.build                                                 0.6s
-[✔] actions.test                                                  0.6s
+[✔] client.filesystem.".".read                                    0.0s
+[✔] actions.deps                                                  1.1s
+[✔] actions.test.script                                           0.0s
+[✔] actions.test                                                  0.0s
+[✔] actions.build.run.script                                      0.0s
+[✔] actions.build.run                                             0.0s
+[✔] actions.build.contents                                        0.0s
+[✔] client.filesystem.build.write                                 0.1s
 ```
 
 Since these actions have run before, they are cached and take less than 1 second to complete.
 
-While the names used for the actions above - `build`, `test` - are short & descriptive,
+While the names used for the actions above - `deps`, `test` & `build` - are short & descriptive,
 any other names would have worked. Put differently, action naming does not affect plan execution.
 
-In the example above, the `build` action is an instance of the yarn package build definition.
-This is written as `build: yarn.#Build`
+In the example above, the `deps` action is an instance of the docker package build definition.
 
-Default definition configuration can be modified via curly brackets, e.g.
+This is written as `deps: docker.#Build`
+
+Default definition configuration - `docker.#Build` in this case - can be modified via curly brackets, e.g.
 
 ```cue
-  actions: {
-    build: yarn.#Build & {
+    deps: docker.#Build & {
       // ...
     }
 ```
 
 We can build complex pipelines efficiently by referencing any definition, from any package in our actions.
-This is one of the fundamental concepts that makes Dagger a powerful devkit for CI/CD.
+This is one of the fundamental concepts that makes Dagger a powerful language for CI/CD.
 Before we can use a package in a plan, we need to declare it at the top of the pipeline configuration, like this:
 
 ```cue
 import (
-  "universe.dagger.io/yarn"
+  "universe.dagger.io/docker"
 )
 ```
 
@@ -71,9 +89,11 @@ Since we are using the plan definition from the dagger package - `dagger.#Plan`
 ```cue
 import (
   "dagger.io/dagger"
-  "universe.dagger.io/yarn"
+  "universe.dagger.io/docker"
 )
 ```
 
-Now that we understand the basics of a Dagger plan, we are ready to learn more about inputs and how to configure them.
-This will enable us to configure plans just-in-time, which is something that typically happanes on every CI run.
+:::tip
+Now that we understand the basics of a Dagger plan, we are ready to learn more about how to interact with the client environment.
+This will enable us to configure plans just-in-time, save build artefacts, and perform other interactions with the environment within which Dagger runs.
+:::