From 02db718a52c32229f111ec7ebc318ee5a9d90179 Mon Sep 17 00:00:00 2001 From: Sinduri Guntupalli Date: Mon, 30 Mar 2026 17:39:57 +0200 Subject: [PATCH 1/2] docs: improve idea template structure and clarity - Consolidate level guidance into a single reference block under ## Levels - Add #### Description section to each level block - Add inline examples and comments for all template sections - Update new-adventure.sh to read Description from level blocks - Update implemented idea (echoes-lost-in-orbit) to match new format - Simplify contributing docs with cp command and 4-step submit flow Signed-off-by: Sinduri Guntupalli --- docs/contributing/adventure-ideas.md | 32 +++++---- ideas/.implemented/echoes-lost-in-orbit.md | 18 +++-- ideas/adventure-idea-template.md | 83 ++++++++++++++++++++-- scripts/new-adventure.sh | 6 +- 4 files changed, 113 insertions(+), 26 deletions(-) diff --git a/docs/contributing/adventure-ideas.md b/docs/contributing/adventure-ideas.md index a702891c..c1f60a24 100644 --- a/docs/contributing/adventure-ideas.md +++ b/docs/contributing/adventure-ideas.md @@ -16,9 +16,13 @@ adventure could look like and what learners would gain from it. ## How to Submit -1. **Copy** `ideas/adventure-idea-template.md` and rename it to `ideas/your-adventure-name.md` -2. **Fill in the template** — replace all placeholders with your idea -3. **[Open a pull request](https://github.com/dynatrace-oss/open-ecosystem-challenges/compare)** with the title `Adventure Idea: [emoji] Your Adventure Name` +1. **Fork** the repository on GitHub +2. **Copy** `ideas/adventure-idea-template.md` and rename it to `ideas/your-adventure-name.md`: + ``` + cp ideas/adventure-idea-template.md ideas/your-adventure-name.md + ``` +3. **Fill in the template** and commit your changes +4. **[Open a pull request](https://github.com/dynatrace-oss/open-ecosystem-challenges/compare)** with the title `Adventure Idea: [emoji] Your Adventure Name` No issue required. Submit your idea directly as a PR. @@ -57,29 +61,29 @@ Strong adventure ideas share these qualities: ## Calibrating Difficulty -The 🟢 Beginner / 🟡 Intermediate / 🔴 Expert labels set participant expectations before they start. Getting this right matters — a mislabeled level is frustrating regardless of which direction it's off. +The 🟢 Beginner / 🟡 Intermediate / 🔴 Expert labels set participant expectations before they start. Getting this right matters - a mislabeled level is frustrating regardless of which direction it's off. Three levels are recommended but not required. A single well-scoped level or a two-level adventure is perfectly valid. ### What each level feels like -**🟢 Beginner** — Get to know the tool. Participants encounter it for the first time and learn the fundamentals: what it does, how it's configured, and what "working" looks like. The challenge is contained and approachable. +**🟢 Beginner** - Get to know the tool. Participants encounter it for the first time and learn the fundamentals: what it does, how it's configured, and what "working" looks like. The challenge is contained and approachable. -**🟡 Intermediate** — Move into systems thinking. Participants have seen the tool before; now they see how it fits into a broader, more realistic setup. The interesting part is the integration — how things connect, interact, and break in non-obvious ways. +**🟡 Intermediate** - Move into systems thinking. Participants have seen the tool before; now they see how it fits into a broader, more realistic setup. The interesting part is the integration - how things connect, interact, and break in non-obvious ways. -**🔴 Expert** — Something genuinely interesting. Not just "harder" — a qualitatively different challenge that rewards deep understanding. Adventure 01 is the best example: Expert isn't just more configuration, it's a completely different observability layer that ties everything together. +**🔴 Expert** - Something genuinely interesting. Not just "harder" - a qualitatively different challenge that rewards deep understanding. Adventure 01 is the best example: Expert isn't just more configuration, it's a completely different observability layer that ties everything together. ### A quick self-check Ask: *Could someone who has read the docs but never used this tool in a real project solve this in under an hour?* - **Yes** → Beginner -- **No — they'd need to understand how two systems interact** → Intermediate -- **No — they'd need to understand the full architecture** → Expert +- **No - they'd need to understand how two systems interact** → Intermediate +- **No - they'd need to understand the full architecture** → Expert ### One level, a few new concepts -A common mistake is packing too much into a single level. Each level should introduce 2–3 new ideas — not a tour of everything the technology can do. +A common mistake is packing too much into a single level. Each level should introduce 2–3 new ideas - not a tour of everything the technology can do. Adventure 01 is a useful reference: Beginner introduces Argo CD ApplicationSets → Intermediate adds Argo Rollouts and PromQL → Expert adds OpenTelemetry Collector and distributed tracing. @@ -87,13 +91,17 @@ Adventure 01 is a useful reference: Beginner introduces Argo CD ApplicationSets A ready-to-use template is available at [`ideas/adventure-idea-template.md`](https://github.com/dynatrace-oss/open-ecosystem-challenges/blob/main/ideas/adventure-idea-template.md). -Copy it, rename it to `ideas/your-adventure-name.md`, and fill in the placeholders. The three-level format is recommended but not required — adjust based on your idea. +Copy it using the command below, fill in the placeholders, and follow the [How to Submit](#how-to-submit) steps above. + +``` +cp ideas/adventure-idea-template.md ideas/your-adventure-name.md +``` See [Echoes Lost in Orbit](https://github.com/dynatrace-oss/open-ecosystem-challenges/blob/main/ideas/.implemented/echoes-lost-in-orbit.md) for a complete example of a well-written idea. ## Writing Good Objectives -Objectives are verifiable outcomes, not tasks. Write them as the state a participant should reach, not the steps they should follow — specific enough that the verification script can check them directly. +Objectives are verifiable outcomes, not tasks. Write them as the state a participant should reach, not the steps they should follow - specific enough that the verification script can check them directly. | Task (avoid) | Outcome (aim for) | |---|---| diff --git a/ideas/.implemented/echoes-lost-in-orbit.md b/ideas/.implemented/echoes-lost-in-orbit.md index 05c8af58..eceea30b 100644 --- a/ideas/.implemented/echoes-lost-in-orbit.md +++ b/ideas/.implemented/echoes-lost-in-orbit.md @@ -12,18 +12,16 @@ **Technologies:** Argo CD, Argo Rollouts, OpenTelemetry, Prometheus, Jaeger, Kubernetes -**Levels:** - -- 🟢 Beginner: Fix a broken multi-environment GitOps setup -- 🟡 Intermediate: Stabilize a failing canary rollout with metrics-based analysis -- 🔴 Expert: Build an observability pipeline to validate traffic before promoting releases - --- ## Levels ### 🟢 Beginner: Broken Echoes +#### Description + +Fix a broken multi-environment GitOps setup + #### Story The Echo Server is misbehaving. Both environments (`staging` and `production`) seem to be down, and messages are silent. The previous engineer left a note saying "I tried to set up this fancy ApplicationSet thing to deploy to both environments at once, but now nothing works." @@ -58,6 +56,10 @@ By the end of this level, the learner should: ### 🟡 Intermediate: The Silent Canary +#### Description + +Stabilize a failing canary rollout with metrics-based analysis + #### Story After fixing the communication outage, the Intergalactic Union welcomed a new species: the Zephyrians. The communications team attempted to deploy their language files using a progressive delivery system, but the rollout is failing. The Zephyrians are still waiting to communicate with the rest of the galaxy. @@ -93,6 +95,10 @@ By the end of this level, the learner should: ### 🔴 Expert: Hyperspace Operations & Transport +#### Description + +Build an observability pipeline to validate traffic before promoting releases + #### Story Word of your progressive release mastery spread across the galaxy. The Bytari, a highly advanced species from the Andromeda sector, want to apply progressive delivery to their mission-critical service: HotROD (Hyperspace Operations & Transport - Rapid Orbital Dispatch), an interstellar ride-sharing service handling dispatch requests across thousands of star systems. diff --git a/ideas/adventure-idea-template.md b/ideas/adventure-idea-template.md index 9b43c419..b60a243a 100644 --- a/ideas/adventure-idea-template.md +++ b/ideas/adventure-idea-template.md @@ -1,8 +1,29 @@ # Adventure Idea: [emoji] [Your Adventure Name] +). + 5. Commit your changes and open a pull request with the title: + Adventure Idea: [emoji] Your Adventure Name + ========================================================================= --> + ## Overview -**Theme:** [2-3 sentences describing the scenario and what's at stake. Who is the learner in this story?] + + +**Theme:** [2-3 sentences describing the scenario and what's at stake] + + **Skills:** @@ -10,20 +31,60 @@ - [Action-oriented skill 2] - [Action-oriented skill 3] -**Technologies:** [Tools involved, e.g., Argo CD, Kubernetes, Prometheus] - -**Levels:** + -- 🟢 Beginner: [One-liner description] -- 🟡 Intermediate: [One-liner description] -- 🔴 Expert: [One-liner description] +**Technologies:** [Tools involved, e.g., Argo CD, Kubernetes, Prometheus] --- ## Levels + + ### 🟢 Beginner: [Level Name] +#### Description + +[One sentence describing what the participant will do in this level] + #### Story [Brief narrative setup for this level] @@ -55,6 +116,10 @@ By the end of this level, the learner should: ### 🟡 Intermediate: [Level Name] +#### Description + +[One sentence describing what the participant will do in this level] + #### Story [Brief narrative setup for this level] @@ -86,6 +151,10 @@ By the end of this level, the learner should: ### 🔴 Expert: [Level Name] +#### Description + +[One sentence describing what the participant will do in this level] + #### Story [Brief narrative setup for this level] diff --git a/scripts/new-adventure.sh b/scripts/new-adventure.sh index 7c6747e3..84b54a97 100755 --- a/scripts/new-adventure.sh +++ b/scripts/new-adventure.sh @@ -107,7 +107,11 @@ extract_level_section() { ' "$selected_file" } -level_summary=$(grep "^- $level_emoji $level_difficulty:" "$selected_file" | sed "s/^- $level_emoji [^:]*: //") +level_summary=$(awk -v level="$selected_level" ' + /^### / { in_level = ($0 == "### " level); next } + in_level && /^#### Description/ { in_desc = 1; next } + in_desc && NF > 0 { print; exit } +' "$selected_file") level_story=$(extract_level_section "Story") level_objective=$(extract_level_section "Objective") level_learnings=$(extract_level_section "What You'll Learn") From 93e0135dc531b27d414e78b0466e911a5b5ef254 Mon Sep 17 00:00:00 2001 From: Sinduri Guntupalli Date: Mon, 30 Mar 2026 17:49:43 +0200 Subject: [PATCH 2/2] docs: improve Levels Signed-off-by: Sinduri Guntupalli --- ideas/adventure-idea-template.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/ideas/adventure-idea-template.md b/ideas/adventure-idea-template.md index b60a243a..9ee4da79 100644 --- a/ideas/adventure-idea-template.md +++ b/ideas/adventure-idea-template.md @@ -8,7 +8,7 @@ cp ideas/adventure-idea-template.md ideas/your-adventure-name.md 3. Replace every [bracketed placeholder] with your content. Keep all formatting (headings, bold labels, etc.) exactly as they appear. - 4. Remove all HTML comments (). + 4. Remove all HTML comments. 5. Commit your changes and open a pull request with the title: Adventure Idea: [emoji] Your Adventure Name ========================================================================= --> @@ -40,14 +40,15 @@ ## Levels