Merge pull request #39 from contino/feature/approvers

updated approvers notes and contributors
contino · Nov 22, 2021 · 44a4dd6 · 44a4dd6
2 parents 072a308 + 199d6d8
commit 44a4dd6
Show file tree

Hide file tree

Showing 2 changed files with 220 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,6 @@
 # Contino learning on Katacoda 
 
-This repo stores the code for the [Katacoda scenarios](https://katacoda.com/contino/) which we're currently using to run our Kubernetes training.
-
-Each `.json` in the parent directory creates a course, which scenarios belong to.
+This repo stores the code for the [Katacoda scenarios](https://katacoda.com/contino/) which we're currently using to run Contino branded training that's available to the public.
 
 ## Contributions
 
@@ -13,9 +11,27 @@ For each scenario, please do the following:
 1. Create a card on the respective [Trello board](https://trello.com/b/7SvNAROB/kubernetes-training)
 1. Work on the scenario, try it out in your own environment `https://www.katacoda.com/$GITHUBHANDLE`
 1. When you're satisfied, send in a pull request.
-1. Next, get two reviews/thumbs up from team members (@mindfulmonk, @joshuatalb and @andresguisado)
+1. Next, get two reviews/thumbs up from approvers
 1. Once your scenario has been reviewed, we will merge it and it will appear on https://katacoda.com/contino
 
+See [contributions.md](contributions.md) for more details, and tips when authoring katacoda lessons.
+
+Be part of the Katacoda slack community at Contino [#practice-katacoda](https://contino.slack.com/archives/C014PLJFBS7).
+
+## Approvers
+
+- Marcus Maxwell - @mindfulmonk
+- Jaroslav Pantsjoha - @jpantsjoha
+- Andres Guisado - @andresguisado (contino alumni) 
+- Andrew Khoury - @drewkhoury
+- Craig Kilpatrick - @ckilpatrick20
+
+**How to approve / what to look for:**
+
+Approvers should review the module as a second set of eyes to ensure it flows well (no issues when walking through the course).
+
+Approvers should also check that content is approriate for Contino branding, given these are public.
+
 ## Resources
 
 View the [Katacoda documentation](https://www.katacoda.com/docs) for information on how to edit environments, scenarios and more.
diff --git a/contributions.md b/contributions.md
@@ -0,0 +1,200 @@
+# How to setup your own Katacoda pipeline
+
+Make sure you create a katacoda account that's linked to your own repo which is a fork of the contino repo. Here why:
+
+- You have full control over all your changes
+- You can deploy and then test your changes
+- You can use/deliver training if you have an immediate need
+- You can inlcude a link to the working scenario in your PR for review
+- There's no other way to deploy/test changes without forking and using your own repo
+- Merging back in is clean 
+
+**eg: Drew's Contino** KataCoda Profile: https://www.katacoda.com/drewkhoury-contino
+
+- Login: Google Account [email protected] 
+- Repo: https://github.com/drewkhoury/katacoda-scenarios-1 (fork of: https://github.com/contino/katacoda-scenarios)
+
+## What if you want to work on your own Katacoda modules independent from Contino?
+
+If you'd like to test katacoda lessons that aren't contino based, or have multiple deployments at once, having independent accounts and github repos is essential (and easy).
+
+You can use a variety of Google, Github and Email accounts for this. eg:
+
+**Drew's Sandbox/Personal:** KataCoda Profile: https://www.katacoda.com/drewkhoury
+- Login: GitHub [email protected] (or I could have used Google Account [email protected])
+- Repo: https://github.com/drewkhoury/katacoda-drewkhoury
+
+
+# Deployments
+
+Useful dashboard links to verify that deployments were successful:
+
+- https://dashboard.katacoda.com/content/
+- https://dashboard.katacoda.com/content/testruns/
+- https://dashboard.katacoda.com/content/debug/
+
+It can take 1 minute, or 20 minutes for deployed courses to show up on your profile.
+
+You can inspect the page and look for "gitCommit" to verify what deployment you're seeing, eg: `<meta name="gitCommit" content="2ef3f7244365837307f9003875e0746f9cd3e825">`
+
+## Viewing your own lesson / debug
+
+When viewing your own lesson you can access debug from the "SCENARIO AUTHORING INFORMATION" link at the top of the page.
+
+e.g: if your background script is downloading software through apt it might look like this:
+
+```
+Warning: Permanently added 'host01,172.17.0.12' (ECDSA) to the list of known hosts. WARNING: apt does not have a stable CLI interface. Use with caution in scripts. Reading package lists... Building dependency tree... Reading state information... The following packages were automatically installed and are no longer required: libc-ares2 libnetplan0 nodejs-doc python3-netifaces Use 'apt autoremove' to remove them. The following additional packages will be installed: ant ant-optional antlr bnd groovy ivy java-wrappers junit4 libantlr-java �� libasm-java libbcel-java libbcpg-java libbcprov-java libbindex-java libbsf-java libbsh-java libcommons-codec-java libcommons-collections3-java � libcommons-compress-java libcommons-lang-java libcommons-logging-java lib
+```
+
+# Tips
+
+View the [Katacoda documentation](https://www.katacoda.com/docs) for information on how to edit environments, scenarios and more. [scenario-examples](https://github.com/katacoda/scenario-examples) github.
+
+## Courses
+
+[Courses](https://www.katacoda.community/essentials/git-repository-structure.html#courses) - each `*-pathway.json` in the parent directory creates a course, which can point to a collection of scenarios.
+
+The scenarios can be grouped by a common subject, and this is represented with a course. A Katacoda course is defined by creating a pathway file. The pathway defines which scenarios should be included in the course and the order to display them.
+
+## Basic Katacoda Syntax in markdown
+
+### Open a file
+
+```
+`relative/path/to/file.foo`{{open}}
+```
+
+### Replace file
+
+```
+<pre class="file" data-filename="relative/path/to/file.foo" data-target="replace">
+you
+multi
+line
+content
+</pre>
+```
+
+### Execute a command
+
+```
+`your command`{{execute}}
+```
+
+### Displaying a Progress Spinner / Wait Script
+
+Example from katacoda: [scenario-examples/displaying-progress-spinner](https://github.com/katacoda/scenario-examples/tree/main/displaying-progress-spinner)
+
+In [foreground.sh](https://github.com/katacoda/scenario-examples/blob/main/displaying-progress-spinner/foreground.sh) they use a `sleep 1` however that could fail (might take a few seconds to load the foreground script). Use this instead:
+
+```
+while [ ! -f /usr/local/bin/wait.sh ]
+do
+  sleep 0.2
+done
+```
+
+Here's an example of how to include the wait script (which needs to be done on the host) alongside other assets in `index.json`:
+```
+    "assets": {
+      "client": [{
+        "file": "*",
+        "target": "~/"
+      }],
+        "host01": [
+            {"file": "wait.sh", "target": "/usr/local/bin/", "chmod": "+x"}
+        ]
+    }  
+```
+
+### VS Code Layout
+
+https://www.katacoda.community/essentials/layouts.html
+
+At the moment, VS Code integration is only supported in our **Ubuntu based environments** but this is being rolled out across all our environments.
+
+### Relative path for files when interacting with editor
+
+You may want to use relative links in your markdown, as well as having a default folder accessable in your IDE.
+
+Let's assume you have the following folder structure in your repo for `scenario-foo`: `assets/folder/path/to/your/app` then you would set your `uieditorpath` to:
+
+```
+  "environment": {
+    "uieditorpath": "/root/folder/path/to/your/app"
+  },  
+```
+
+Then you can do things like this:
+
+```
+`relative/path/to/file.foo`{{open}}
+```
+
+Instead of:
+
+```
+`/root/folder/path/to/your/app/relative/path/to/file.foo`{{open}}
+```
+
+### Sample `index.json`
+
+This is an example of an `index.json` skeleton.
+
+Files that need to live in the root of the lesson repo (alongside `index.json`):  
+
+- steps/intro/finish: `*.md`
+- courseData: `background.sh` (katacoda runs this script you specify in the background on lesson-start)
+- code: `foreground.sh` (katacoda runs this script you specify in the forground on lesson-start)
+
+Files that need to live in the `assets/` folder in the lesson repo:
+
+- `wait.sh` this needs to be available in the terminal (if you want to support progress spinner feature), so we include it in `assets/` and copy it to `host01`
+- anything else we need available for our lesson, in our example we have `assets/folder/path/to/your/app` which contains our application
+
+ ```
+ {
+  "title": "My Senario",
+  "description": "My Senario",
+  "difficulty": "Beginner",
+  "time": "30 minutes",
+  "icon": "fa-java",
+  "details": {
+    "steps": [
+      {
+        "title": "Step 1",
+        "text": "step1.md"
+      },
+      {
+        "title": "Step 2",
+        "text": "step2.md"
+      }
+    ],
+    "intro": {
+      "text": "intro.md",
+      "courseData": "background.sh",
+      "code": "foreground.sh"
+    },
+    "finish": {
+      "text": "finish.md"
+    },
+    "assets": {
+      "client": [{
+        "file": "*",
+        "target": "~/"
+      }],
+        "host01": [
+            {"file": "wait.sh", "target": "/usr/local/bin/", "chmod": "+x"}
+        ]
+    }
+  },
+  "environment": {
+    "uieditorpath": "/root/folder/path/to/your/app",
+    "uilayout": "vscode-terminal-split"
+  },
+  "backend": {
+    "imageid": "ubuntu:2004"
+  }
+}
+ ```