From 1dacc3b9996acf54ae9604b32b48312ae00bfe8f Mon Sep 17 00:00:00 2001
From: Cory Latschkowski <koree@redhat.com>
Date: Sat, 16 Sep 2023 18:35:02 -0500
Subject: [PATCH] add: practices doc

---
 .wordlist-md      | 11 +++++++
 docs/PRACTICES.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 88 insertions(+)
 create mode 100644 docs/PRACTICES.md

diff --git a/.wordlist-md b/.wordlist-md
index 5ff00895..05ada87a 100644
--- a/.wordlist-md
+++ b/.wordlist-md
@@ -82,6 +82,7 @@ UI
 Weaviate
 Workspaces
 ack
+addr
 adhoc
 adm
 alongsecret
@@ -110,6 +111,7 @@ cli
 clientSecret
 clusterissuer
 clusterrolebinding
+conf
 config
 configmap
 configs
@@ -141,6 +143,7 @@ godmode
 gp
 gpus
 grafana
+gui
 homelab
 html
 htpass
@@ -193,12 +196,14 @@ oc
 ocp
 ocs
 odf
+ok
 opendatahub
 openshift
 opentlc
 operatorGroup
 operatorGroups
 patchesJson
+podman
 popd
 postgres
 pre
@@ -207,11 +212,16 @@ priorityclass
 prometheus
 pushd
 pvc
+pwd
 quickstart
 rbac
+rc
+rcd
+rclone
 redhat
 redistributions
 repo
+reusability
 rhdp
 rhel
 rhods
@@ -242,6 +252,7 @@ sublicense
 tekton
 templating
 thanos
+tmp
 traefik
 triggerer
 useable
diff --git a/docs/PRACTICES.md b/docs/PRACTICES.md
new file mode 100644
index 00000000..ff01c4b1
--- /dev/null
+++ b/docs/PRACTICES.md
@@ -0,0 +1,77 @@
+# Recommended Practices (Draft)
+
+Below are recommended practices or references.
+
+## Building Demos
+
+Common cli tools across platforms:
+
+- `git`
+- `bash`
+- `oc` / `kubectl`
+- `python` (v3)
+
+Considerations
+
+- ALWAYS **start** with a `README.md`
+  - One sentence is ok
+  - Ex: Title: Weather Toaster, Body: I want to build a toaster that controls the weather
+  - ALWAYS commit to `git` - do you see what I did there? :)
+  - Use a public `git` location - We can always rewrite (git) history to make it look perfect
+- One click solutions - Ex: `scripts/bootstrap.sh`
+  - Offer a solution that takes less than 5 minutes of user interaction to complete (your automation can take longer)
+  - Exception: When you are building training into your demo
+- Make friends / Collaborate - Have ~~strange people~~ others test your work
+  - Regular peer reviews (short and frequent)
+  - 3 days max between peer review
+  - Goal: avoid *"it worked on my machine..."*
+- Modular design - Build for reuse
+  - *How can I make this easy for someone to reuse my work?*
+
+Architecture
+
+- Assume minimum privilege for the user / demo
+  - Ex: may only have access to namespace vs `cluster-admin`
+  - Use appropriate role bindings (avoid admin)
+- Use the minimum number of cli tools and dependencies
+- Scripting - avoid complex functions (`bash`, `python`, `Makefile`)
+  - Attempt to show commands for manual operations
+  - Use functions for reusability
+  - *Can I cut and paste?*
+
+## Data Science
+
+Recommendations
+
+- Data sets as container images
+  - Use a container to store your data set
+  - Serve via `http` protocol - `s3`, `webdav`
+    - `minio`, `rclone serve`, `httpd`
+  - Push to public repo (`quay.io`, `ghcr.io`)
+
+TODO
+
+- Build an example of containerizing a data set
+
+```
+RC_USER=admin
+RC_PASS=rclone
+
+cat > rclone.conf <<CONFIG
+[local]
+type = local
+CONFIG
+
+podman run \
+  -it \
+  --rm \
+  -v $(pwd):/data \
+  -p 8080:8080 \
+  docker.io/rclone/rclone \
+    rcd \
+    --config /tmp/rclone.conf \
+    --rc-web-gui \
+    --rc-addr :8080 \
+    --rc-user ${RC_USER} \
+    --rc-pass ${RC_PASS}
+```