Merge pull request #20 from IObert/master

Update before Codejam Vienna

Author: qmacro

exercises/01/readme.md

@@ -43,31 +43,31 @@ user-agent = "npm/6.4.1 node/v10.15.3 linux x64"
 ; "npm config ls -l" to show all defaults.
 ```
 
-:point_right: Next, explore the information about the `@sap/cds` package, including its dependencies, with:
+:point_right: Next, explore the information about the `@sap/cds-dk` (the dk stands for development kit)package, including its dependencies, with:
 
 ```sh
 user@host:~
-=> npm info @sap/cds
+=> npm info @sap/cds-dk
 ```
 
 This will show you that it has dependencies on other `@sap` namespaced packages, and also that there is a 'binary' (in other words an executable) called `cds` that's delivered as part of the package.
 
-:point_right: Now, install the `@sap/cds` package globally:
+:point_right: Now, install the `@sap/cds-dk` package globally:
 
 ```sh
 user@host:~
-=> npm install --global @sap/cds
+=> npm install --global @sap/cds-dk
 ```
 
 This should eventually produce output similar to this:
 
 ```sh
-/Users/i347491/.nvm/versions/node/v10.16.3/bin/cds -> /Users/i347491/.nvm/versions/node/v10.16.3/lib/node_modules/@sap/cds/bin/cds.js
-+ @sap/cds@3.18.3
-added 69 packages from 144 contributors in 6.416s
+/Users/d056949/.nvm/versions/node/v10.15.3/bin/cds -> /Users/d056949/.nvm/versions/node/v10.15.3/lib/node_modules/@sap/cds-dk/bin/cds.js
++ @sap/cds-dk@1.1.4
+updated 1 package in 27.076s
 ```
 
-Here you can see that the version of the `@sap/cds` package installed is 3.18.3. It may be that the version of `@sap/cds` that is installed when you do this exercise will be different (newer).
+Here you can see that the version of the `@sap/cds-dk` package installed is 3.18.4. It may be that the version of `@sap/cds-dk` that is installed when you do this exercise will be different (newer).
 
 ### 2. Install the CDS extension for VS Code
 
@@ -110,7 +110,7 @@ npx check-sap-cloud-readiness -codejam-cap
 You should see an output similar to this:
 ![out](output.png)
 
-If necessary, double check the [prerequisites](../../prerequisites.md) to install the missing tools. Please contact the instructor of this CodeJam if you need help.
+If necessary, double check the [prerequisites](../../prerequisites.md)  to install the missing tools. Please contact the instructor of this CodeJam if you need help.
 
 
 ## Summary
@@ -120,9 +120,13 @@ You've now installed the key tools for developing with CAP locally, and are all
 ## Questions
 
 1. What are the benefits of using NPM here?
+<!--- easy to user and de-facto standard --->
 
-1. What are the `@sap` namespaced packages upon which `@sap/cds` depends?
+2. What are the `@sap` namespaced packages upon which `@sap/cds-dk` depends?
+<!--- cds-sidecar-client, edm-converters, cds, generator-cds --->
 
-1. What is the significance of using the `--global` option when installing the `@sap/cds` package?
+3. What is the significance of using the `--global` option when installing the `@sap/cds-dk` package?
+<!--- globally available --->
 
-1. What is the meaning of the `.vsix` file type for the VS Code extension? Can we dig into that to see what's inside?
+4. What is the meaning of the `.vsix` file type for the VS Code extension? Can we dig into that to see what's inside?
+<!--- VSI (Visual Studio Installer) and with most things, we tacked an "x" on the end, unzip, contains extension (node app), manifest and xml --->

exercises/01/vscode-extension-import.png

@@ -98,7 +98,7 @@ user@host:~
 => code bookshop
 ```
 
-If this approach is not available to you, simply start VS Code through your operating system's GUI and open the directory manually (with menu path "File → Open").
+> If this approach is not available to you, simply start VS Code through your operating system's GUI and open the directory manually (with menu path "File → Open").
 
 
 ### 3. Explore the initialized project structure
@@ -115,7 +115,7 @@ Briefly, the directories and contents can be described thus:
 | -------------- | -------- |
 | `.vscode` | VS Code specific files for launch configurations (useful for debugging, which we will cover in [exercise 08](../08/)) |
 | `db` | Where the data models (in CDS) are specified. |
-| `node_modules` | This is the normal place where NPM packages (modules) are to be found in a Node.js based project |
+| `node_modules` | This is the place where NPM packages (modules) are to be found in a Node.js based project |
 | `srv` | Where the service definitions (in CDS) are specified. |
 | `mta.yaml` | This is the central descriptor file for the project. It defines all modules (microservices) and backing services (like databases). This information will be used to build the .mtar archive during design time and to deploy & provision the apps and services during deploy time. |
 
@@ -168,6 +168,9 @@ This should open up the terminal at the bottom of VS Code like this:
 
 ![integrated terminal in view](integrated-terminal-in-view.png)
 
+> **Windows users:** Please make sure to select `cmd` as your default shell before you continue:
+![default shell](default-shell-windows.png)
+
 :point_right: In the integrated terminal, use the `cds` command line tool with the `serve` command to start serving. Specify `all`, like this, so that `cds` will look for appropriate configuration to serve:
 
 ```sh
@@ -215,10 +218,14 @@ With a single command, you've initialized a basic OData service project and with
 
 ## Questions
 
-1. Why is there an focus on "TTM" (time to metadata) - what advantages does that bring?
+1. Why is there an focus on "Contracts First" (As all you need to run a service is a service definition) - what advantages does that bring?
+<!--- UI teams can start to work right away --->
 
-1. What is the difference between the data model and the service definition? Why do we need both?
+2. What is the difference between the data model and the service definition? Why do we need both?
+<!--- db model for schema, service for access (control) --->
 
-1. What is returned in response to a request for the Books entityset resource right now?
+3. What is returned in response to a request for the Books entityset resource right now?
+<!--- error --->
 
-1. What happened to the `cds` process when you accessed the entityset? Can you think of reasons why this happened?
+4. What happened to the `cds` process when you accessed the entityset? Can you think of reasons why this happened?
+<!--- crash --->

exercises/02/default-shell-windows.png

@@ -290,7 +290,10 @@ You now have a fully functional, albeit simple, OData service backed by a persis
 ## Questions
 
 1. What are other possible targets in the compilation context?
+<!--- yaml, edmx, when inspecting cdsc you can find hana,odata,cds,swager,sql,csn as well --->
 
-1. What is the thinking behind the use of views at the service definition layer and tables at the data model layer?
+2. What is the thinking behind the use of views at the service definition layer and tables at the data model layer?
+<!--- different consumers on the same data (APIs, UIs), leverage features of a view, separation of concerns, --->
 
-1. Why might you use the `cds compile` command at all?
+3. Why might you use the `cds compile` command at all?
+<!--- to understand what happens under the hood when you run cds deploy --->

exercises/02/readme.md

@@ -76,5 +76,7 @@ Your OData service now has sample data that you can access via OData operations.
 ## Questions
 
 1. Does the order of the fields defined in the CSV files have to match the order of the properties defined in the entities in the data model?
+<!--- nope, databases work on sets --->
 
-1. Where do you think the format of the CSV file names has come from?
+2. Where do you think the format of the CSV file names has come from?
+<!--- namespace + table name --->

exercises/03/readme.md

@@ -155,8 +155,6 @@ user@host:~/bookshop
 [cds] - launched in: 722.087ms
 ```
 
-> If you're running Windows, you can use a double-semicolon (;;) in place of the `&&`. It's not quite the same but will work just fine in most cases.
-
 
 ### 5. Examine what the Orders entity looks like now
 
@@ -262,8 +260,11 @@ At this point you have a meaningful OData service with data and against which yo
 
 ## Questions
 
-1. We added a field `country` described by the type `Country`. What exactly is this type, and what does it bring about in the resulting service's metadata?
-
 1. Did you notice an extra line in the output of `cds serve all` after the addition of the reference to `@sap/cds/common`?
+<!--- node_modules/@sap/cds/common.cds --->
+
+2. We added a field `country` described by the type `Country`. What exactly is this type, and what does it bring about in the resulting service's metadata?
+<!--- string(3), code list --->
 
-1. Are there any issues with the way we have set up the service definition right now?
+3. Are there any issues with the way we have set up the service definition right now?
+<!--- all public --->

exercises/04/readme.md

@@ -45,7 +45,7 @@ curl \
  http://localhost:4004/catalog/Books
 ```
 
-Check that the creation requests are successful, and that you can see the new author and book in an OData Query operation: [http://localhost:4004/catalog/Authors?$expand=books](http://localhost:4004/catalog/Authors?$expand=books).
+Check that the creation requests are successful, and that you can see the new author and book in an OData Query operation: <http://localhost:4004/catalog/Authors?$expand=books>.
 
 
 ### 3. Restrict access to the Books and Authors entities
@@ -187,6 +187,11 @@ In this exercise you used shortcut annotations to restrict access to the entitie
 
 ## Questions
 
-1. How might the annotations relating to the read-only restrictions be useful in a UI context?
+1. Did you notice anything special about your request to <http://localhost:4004/catalog/Authors?$expand=books> in step 2?
+<!--- expand call --->
 
-1. What was the format of the OData Delete operation - did we need to supply a payload?
+2. How might the annotations relating to the read-only restrictions be useful in a UI context?
+<!--- FE autorenders (or hides) component depending on metadata --->
+
+3. What was the format of the OData Delete operation - did we need to supply a payload?
+<!--- nope, because of REST --->

exercises/05/readme.md

@@ -102,5 +102,7 @@ It's easy to explore building different views on the same underlying data model,
 ## Questions
 
 1. Why might it be better to specify properties to _exclude_, rather than properties to _include_?
+<!-- depending on the data model, how many "unused" properties you have -->
 
-1. What did the order creation HTTP requests look like - which service was used, and why?
+2. What did the order creation HTTP requests look like - which service was used, and why?
+<!-- used the old one -->

exercises/06/readme.md

@@ -165,7 +165,10 @@ You have added custom logic and learned how to debug a service in VS Code. The o
 ## Questions
 
 1. What other hooks do you think might be useful in customizing a service?
+<!-- before CRUD, after CRUD -->
 
-1. What is the command used in the launch configuration for starting the service in debug mode - is it `cds serve all`?
+2. What is the command used in the launch configuration for starting the service in debug mode - is it `cds serve all`?
+<!-- cds run in memory with inspect breakpoint --->
 
-1. How many times is the function (that is supplied to the `after` hook) called?
+3. How many times is the function (that is supplied to the `after` hook) called?
+<!-- 1 -->