From 096a5c3bfde7e31cc3189aca1d246e92272d9b82 Mon Sep 17 00:00:00 2001 From: Sinduri Guntupalli Date: Fri, 27 Mar 2026 15:03:24 +0100 Subject: [PATCH] feat(ideas): improve idea lifecycle, folder structure, and contributing docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Introduce ideas/ folder structure with adventure-idea-template.md - Update new-adventure.sh to read from ideas/ root (excluding template) - Update idea-tracking-issue workflow to trigger on ideas/ root additions - Simplify lifecycle: ideas/ root → ideas/.implemented/ when built - Improve adventure-ideas.md and adventures.md for clarity and flow - Update PR template checklist to reflect new lifecycle Signed-off-by: Sinduri Guntupalli --- .github/workflows/idea-tracking-issue.yml | 2 + docs/contributing/adventure-ideas.md | 126 ++++++---------------- docs/contributing/adventures.md | 4 +- ideas/adventure-idea-template.md | 114 ++++++++++++++++++++ scripts/new-adventure.sh | 2 +- 5 files changed, 154 insertions(+), 94 deletions(-) create mode 100644 ideas/adventure-idea-template.md diff --git a/.github/workflows/idea-tracking-issue.yml b/.github/workflows/idea-tracking-issue.yml index 85a3c68e..f3c604cc 100644 --- a/.github/workflows/idea-tracking-issue.yml +++ b/.github/workflows/idea-tracking-issue.yml @@ -26,6 +26,8 @@ jobs: f.status === 'added' && f.filename.startsWith('ideas/') && !f.filename.startsWith('ideas/.implemented/') && + f.filename.split('/').length === 2 && + f.filename !== 'ideas/adventure-idea-template.md' && f.filename.endsWith('.md') ); if (!ideaFile) { diff --git a/docs/contributing/adventure-ideas.md b/docs/contributing/adventure-ideas.md index 149b23bb..a702891c 100644 --- a/docs/contributing/adventure-ideas.md +++ b/docs/contributing/adventure-ideas.md @@ -7,14 +7,42 @@ adventure could look like and what learners would gain from it. ## Before You Start -- **Check existing ideas.** - Browse [adventure idea issues](https://github.com/dynatrace-oss/open-ecosystem-challenges/issues?q=is%3Aissue+is%3Aopen+label%3A%22adventure+idea%22) - and [open PRs](https://github.com/dynatrace-oss/open-ecosystem-challenges/pulls) to avoid duplicates. +- **Check existing ideas.** Browse [adventure idea issues](https://github.com/dynatrace-oss/open-ecosystem-challenges/issues?q=is%3Aissue+is%3Aopen+label%3A%22adventure+idea%22) + and [open PRs](https://github.com/dynatrace-oss/open-ecosystem-challenges/pulls) to make sure your idea hasn't already been submitted or is in the pipeline. - **Focus on actions, not tools.** Frame challenges around what learners will *do* (e.g., "release safely", "observe AI systems") rather than tools they'll use (e.g., "Argo Rollouts", "OpenTelemetry"). - **Consider multiple levels.** Three levels (Beginner, Intermediate, Expert) are recommended but not required. Even a single well-designed level is valuable. +## 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` + +No issue required. Submit your idea directly as a PR. + +## From Idea to Adventure + +After you open a PR: + +1. **Review.** Maintainers review your idea for fit and feasibility. +2. **Feedback.** We may suggest adjustments or ask clarifying questions. +3. **Approval.** Once approved and merged, your idea becomes available for implementation via `make new-adventure`. +4. **Implementation.** You or another contributor picks it up, builds it, and the idea moves to `ideas/.implemented/`. + +You're welcome to implement your own idea after approval, but there's no obligation to do so. + +### Idea Folder Structure + +Ideas are organized by their status: + +``` +ideas/ +├── [your-idea].md # Proposals & approved ideas (submitted via PR) +└── .implemented/ # Completed adventures (reference only) +``` + ## What Makes a Good Adventure Idea? Strong adventure ideas share these qualities: @@ -55,86 +83,13 @@ A common mistake is packing too much into a single level. Each level should intr Adventure 01 is a useful reference: Beginner introduces Argo CD ApplicationSets → Intermediate adds Argo Rollouts and PromQL → Expert adds OpenTelemetry Collector and distributed tracing. -## How to Submit - -1. **Create a new file** in `ideas/` named `your-adventure-name.md` -2. **Use the template** below to describe 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` - -No issue required. Submit your idea directly as a PR. - ## Adventure Idea Template -Use this structure for your proposal. The three-level format is recommended but not required. Adjust based on your idea. - -```markdown -# 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?] - -**Skills:** - -- [Action-oriented skill 1, e.g., "Deploy reliably across multiple environments"] -- [Action-oriented skill 2] -- [Action-oriented skill 3] - -**Technologies:** [Tools involved, e.g., Argo CD, Kubernetes, Prometheus] +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). -**Levels:** +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. -- 🟢 Beginner: [One-liner description] -- 🟡 Intermediate: [One-liner description] -- 🔴 Expert: [One-liner description] - ---- - -## Levels - -### 🟢 Beginner: [Level Name] - -#### Story - -[Brief narrative setup for this level] - -#### The Problem - -[What's broken or misconfigured? Be specific enough for an implementer, but don't reveal the solution.] - -#### Objective - -By the end of this level, the learner should: - -- [Concrete, verifiable outcome 1] -- [Concrete, verifiable outcome 2] -- [Concrete, verifiable outcome 3] - -> See **Writing Good Objectives** below the template for guidance on what makes a strong objective. - -#### What You'll Learn - -- [Specific concept 1] -- [Specific concept 2] -- [Specific concept 3] - -#### Tools & Infrastructure - -- **Tools:** [CLI tools, e.g., kubectl, argocd CLI] -- **Infrastructure:** [What needs to run, e.g., Kubernetes Cluster, Argo CD] - ---- - -### 🟡 Intermediate: [Level Name] - -[Same structure as Beginner] - ---- - -### 🔴 Expert: [Level Name] - -[Same structure as Beginner] -``` +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 @@ -145,16 +100,3 @@ Objectives are verifiable outcomes, not tasks. Write them as the state a partici | Fix the ApplicationSet | See two distinct Applications in the Argo CD dashboard | | Add instrumentation | Send traces to the OpenTelemetry Collector at `http://localhost:30107` | -## Example - -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 an implemented adventure idea. - -## What Happens Next? - -1. **Review.** Maintainers review your idea for fit and feasibility. -2. **Feedback.** We may suggest adjustments or ask clarifying questions. -3. **Approval.** Once approved, your idea becomes available for implementation. -4. **Implementation.** You or another contributor can pick it up and build it. - -You're welcome to implement your own idea after approval, but there's no obligation to do so. diff --git a/docs/contributing/adventures.md b/docs/contributing/adventures.md index dc7c2062..7eac8751 100755 --- a/docs/contributing/adventures.md +++ b/docs/contributing/adventures.md @@ -4,8 +4,10 @@ Ready to turn an approved idea into a full adventure? This guide walks you throu ## Before You Start -- **Pick an approved idea.** Browse [adventure idea issues](https://github.com/dynatrace-oss/open-ecosystem-challenges/issues?q=is%3Aissue+is%3Aopen+label%3A%22adventure+idea%22) and comment to claim one. Have your own idea? [Submit it first](adventure-ideas.md). +- **Pick an approved idea.** Browse [open implementation issues](https://github.com/dynatrace-oss/open-ecosystem-challenges/issues?q=is%3Aissue+is%3Aopen+label%3A%22adventure+idea%22) to find unclaimed ideas. Once you pick one, comment on its issue to claim it. - **Read the idea thoroughly.** Understand the story, objectives, and learning outcomes. +- **Have your own idea?** [Propose it](adventure-ideas.md) — ideas go through review before they're available for implementation. +- **Ready to build?** Once an idea is approved and merged into `ideas/`, it's available via `make new-adventure`. ## What You'll Build diff --git a/ideas/adventure-idea-template.md b/ideas/adventure-idea-template.md new file mode 100644 index 00000000..9b43c419 --- /dev/null +++ b/ideas/adventure-idea-template.md @@ -0,0 +1,114 @@ +# 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?] + +**Skills:** + +- [Action-oriented skill 1, e.g., "Deploy reliably across multiple environments"] +- [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] + +--- + +## Levels + +### 🟢 Beginner: [Level Name] + +#### Story + +[Brief narrative setup for this level] + +#### The Problem + +[What's broken or misconfigured? Be specific enough for an implementer, but don't reveal the solution.] + +#### Objective + +By the end of this level, the learner should: + +- [Concrete, verifiable outcome 1] +- [Concrete, verifiable outcome 2] +- [Concrete, verifiable outcome 3] + +#### What You'll Learn + +- [Specific concept 1] +- [Specific concept 2] +- [Specific concept 3] + +#### Tools & Infrastructure + +- **Tools:** [CLI tools, e.g., kubectl, argocd CLI] +- **Infrastructure:** [What needs to run, e.g., Kubernetes Cluster, Argo CD] + +--- + +### 🟡 Intermediate: [Level Name] + +#### Story + +[Brief narrative setup for this level] + +#### The Problem + +[What's broken or misconfigured? Be specific enough for an implementer, but don't reveal the solution.] + +#### Objective + +By the end of this level, the learner should: + +- [Concrete, verifiable outcome 1] +- [Concrete, verifiable outcome 2] +- [Concrete, verifiable outcome 3] + +#### What You'll Learn + +- [Specific concept 1] +- [Specific concept 2] +- [Specific concept 3] + +#### Tools & Infrastructure + +- **Tools:** [CLI tools, e.g., kubectl, argocd CLI] +- **Infrastructure:** [What needs to run, e.g., Kubernetes Cluster, Argo CD] + +--- + +### 🔴 Expert: [Level Name] + +#### Story + +[Brief narrative setup for this level] + +#### The Problem + +[What's broken or misconfigured? Be specific enough for an implementer, but don't reveal the solution.] + +#### Objective + +By the end of this level, the learner should: + +- [Concrete, verifiable outcome 1] +- [Concrete, verifiable outcome 2] +- [Concrete, verifiable outcome 3] + +#### What You'll Learn + +- [Specific concept 1] +- [Specific concept 2] +- [Specific concept 3] + +#### Tools & Infrastructure + +- **Tools:** [CLI tools, e.g., kubectl, argocd CLI] +- **Infrastructure:** [What needs to run, e.g., Kubernetes Cluster, Argo CD] diff --git a/scripts/new-adventure.sh b/scripts/new-adventure.sh index 89be0f8c..7c6747e3 100755 --- a/scripts/new-adventure.sh +++ b/scripts/new-adventure.sh @@ -6,7 +6,7 @@ IDEAS_DIR="$REPO_ROOT/ideas" # ─── Select adventure ──────────────────────────────────────────────────────── -selected_slug=$(find "$IDEAS_DIR" -maxdepth 1 -name "*.md" -exec basename {} .md \; | sort \ +selected_slug=$(find "$IDEAS_DIR" -maxdepth 1 -name "*.md" ! -name "adventure-idea-template.md" -exec basename {} .md \; | sort \ | gum choose --header "Which adventure do you want to scaffold?") selected_file="$IDEAS_DIR/$selected_slug.md" adventure_header=$(grep -m1 '^# Adventure Idea:' "$selected_file" | sed 's/^# Adventure Idea: *//')