diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh index 990b2d23..018ec597 100644 --- a/.devcontainer/post-create.sh +++ b/.devcontainer/post-create.sh @@ -3,8 +3,5 @@ set -euo pipefail lib/shared/init.sh --version v0.17.0 # https://github.com/charmbracelet/gum/releases -echo "โ†’ Installing mkdocs-material..." -pip install --quiet mkdocs-material mkdocs-monorepo-plugin - -echo "โœ“ Done! Run 'mkdocs serve' to start the docs server." +echo "โœ“ Done!" diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index 2250fdee..a25b2f56 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -33,6 +33,6 @@ body: attributes: label: Where? description: Link to the relevant page, file, or adventure level. - placeholder: "e.g. https://dynatrace-oss.github.io/open-ecosystem-challenges/01-echoes-lost-in-orbit/beginner" + placeholder: "e.g. https://offon.dev/adventures/echoes-lost-in-orbit/levels/beginner" validations: required: true diff --git a/.github/ISSUE_TEMPLATE/improvement.yml b/.github/ISSUE_TEMPLATE/improvement.yml index a0188b90..6ea72f18 100644 --- a/.github/ISSUE_TEMPLATE/improvement.yml +++ b/.github/ISSUE_TEMPLATE/improvement.yml @@ -15,7 +15,7 @@ body: attributes: label: Where? description: Link to the relevant page, file, or adventure level. - placeholder: "e.g. https://dynatrace-oss.github.io/open-ecosystem-challenges/01-echoes-lost-in-orbit/beginner" + placeholder: "e.g. https://offon.dev/adventures/echoes-lost-in-orbit/levels/beginner" validations: required: true - type: textarea diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml deleted file mode 100644 index 2c81e638..00000000 --- a/.github/workflows/deploy-docs.yaml +++ /dev/null @@ -1,30 +0,0 @@ -# See https://squidfunk.github.io/mkdocs-material/publishing-your-site/#with-github-actions -name: Deploy Documentation -on: - push: - branches: - - main -permissions: - contents: write -jobs: - deploy: - # Pages deploy is not necessary in forks - if: ${{ github.repository == 'dynatrace-oss/open-ecosystem-challenges' }} - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Configure Git Credentials - run: | - git config user.name github-actions[bot] - git config user.email 41898282+github-actions[bot]@users.noreply.github.com - - name: Setup Python - uses: actions/setup-python@v5 - with: - python-version: 3.x - - name: Install Plugins - run: | - pip install mkdocs-material - pip install mkdocs-monorepo-plugin - - name: Deploy Documentation - run: mkdocs gh-deploy --force \ No newline at end of file diff --git a/.github/workflows/idea-tracking-issue.yml b/.github/workflows/idea-tracking-issue.yml index f3c604cc..7c7083f1 100644 --- a/.github/workflows/idea-tracking-issue.yml +++ b/.github/workflows/idea-tracking-issue.yml @@ -55,7 +55,7 @@ jobs: '', '## Want to build it?', '', - 'Comment on this issue to claim it, then follow the [Building Adventures](https://dynatrace-oss.github.io/open-ecosystem-challenges/contributing/adventures/) guide.', + 'Comment on this issue to claim it, then follow the [Building Adventures](https://github.com/dynatrace-oss/open-ecosystem-challenges/blob/main/CONTRIBUTING.md#build-a-new-adventure) guide.', '', '**Each level should be a separate PR.** Reference this issue with `Part of #` in earlier PRs and `Closes #` in the final one.', ].join('\n'), diff --git a/.github/workflows/walkthrough-issues.yml b/.github/workflows/walkthrough-issues.yml index d18e5887..e904b110 100644 --- a/.github/workflows/walkthrough-issues.yml +++ b/.github/workflows/walkthrough-issues.yml @@ -66,7 +66,7 @@ jobs: '', '## How to contribute', '', - 'Comment on this issue to claim it, then follow the [Solution Walkthroughs](https://dynatrace-oss.github.io/open-ecosystem-challenges/contributing/solution-walkthroughs/) guide.', + 'Comment on this issue to claim it, then follow the [Solution Walkthroughs](https://github.com/dynatrace-oss/open-ecosystem-challenges/blob/main/CONTRIBUTING.md#write-a-solution-walkthrough) guide.', '', 'A walkthrough can be:', "- **External content** โ€” a blog post, video, or any public resource. Link to it from the adventure's solutions page.", diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1377ff29..6f5fdb83 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,22 +1,361 @@ # Contributing Guide -Thank you for considering contributing to the Open Ecosystem Challenges! ๐ŸŽ‰ +Thank you for your interest in contributing to Open Ecosystem Challenges! -Whether you're here to fix a typo, suggest an adventure idea, or build an entire challenge, your contribution matters. - -๐Ÿ“– **[Read the full Contributing Guide](https://dynatrace-oss.github.io/open-ecosystem-challenges/contributing/)** for -everything you need to get started. +Whether you're fixing a typo, proposing an adventure idea, or building an entire challenge, your contribution matters. ## Ways to Contribute -| Type | Description | -|----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------| -| โœจ [Improvements & Bug Fixes](https://dynatrace-oss.github.io/open-ecosystem-challenges/contributing/) | Improve docs, enhance challenge setup, fix bugs | -| ๐Ÿ’ก [Adventure Ideas](https://dynatrace-oss.github.io/open-ecosystem-challenges/contributing/adventure-ideas/) | Propose a new adventure with a full implementation plan | -| ๐Ÿ—๏ธ [New Adventures](https://dynatrace-oss.github.io/open-ecosystem-challenges/contributing/adventures/) | Build and implement a full adventure based on an approved idea | -| ๐Ÿ“– [Solution Walkthroughs](https://dynatrace-oss.github.io/open-ecosystem-challenges/contributing/solution-walkthroughs/) | Write a step-by-step guide for a completed challenge | +| Type | Description | Guide | +|-------------------------------|----------------------------------------------------------------|-----------------------------------------------------| +| โœจ Improvements & Bug Fixes | Improve docs, enhance challenge setup, fix bugs | This page | +| ๐Ÿ’ก Adventure Ideas | Propose a new adventure with a full implementation plan | [Adventure Ideas](#propose-an-adventure-idea) | +| ๐Ÿ—๏ธ New Adventures | Build and implement a full adventure based on an approved idea | [Building Adventures](#build-a-new-adventure) | +| ๐Ÿ“– Solution Walkthroughs | Write a step-by-step guide for a completed challenge | [Solution Walkthroughs](#write-a-solution-walkthrough) | + +## Code of Conduct + +This project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). Be respectful and constructive. + +## Before You Start + +1. **Check existing issues.** Search [open issues](https://github.com/dynatrace-oss/open-ecosystem-challenges/issues) before creating a new one. +2. **Determine if you need an issue:** + - **Small fixes** (typos, broken links): No issue needed, just open a PR. + - **Larger improvements & bug fixes**: Open an issue first to discuss. + - **Adventure ideas**: No issue needed, submit your idea directly as a PR. + - **New adventures & solution walkthroughs**: Pick up an existing issue. +3. **Claim the issue.** If working on an existing issue, comment to let others know you're on it. + +## Pull Request Process + +1. **Fork the repository** and create your branch from `main`. +2. **Make your changes** with clear, focused commits. +3. **Test your changes.** Run verification scripts if applicable. +4. **Open a pull request** with a clear description of what you changed and why. +5. **Address feedback.** Maintainers will review and may request changes. + +Keep PRs focused. Smaller, single-purpose PRs are easier to review and merge. + +## Developer Certificate of Origin (DCO) + +This project uses the [Developer Certificate of Origin](https://developercertificate.org/) (DCO). All commits must be signed off to certify that you have the right to submit the code and agree to the DCO terms. + +Sign off your commits by adding `-s` to your commit command: + +```bash +git commit -s -m "Your commit message" +``` + +If you've already made commits without signing off, you can amend them: + +```bash +git commit --amend -s --no-edit +git push --force-with-lease +``` + +The DCO is enforced automatically via [cncf/dco2](https://github.com/cncf/dco2). PRs without signed-off commits will be flagged. ## Getting Help -- ๐Ÿ’ญ [Community forum](https://community.open-ecosystem.com/c/challenges/builders/40) -- ๐Ÿ› [Open an issue](https://github.com/dynatrace-oss/open-ecosystem-challenges/issues) +- **Ideas & bugs?** [Open an issue](https://github.com/dynatrace-oss/open-ecosystem-challenges/issues) +- **Questions & discussions?** [Open Ecosystem Community](https://community.open-ecosystem.com/c/challenges) + +## License + +This project is licensed under the [MIT License](https://github.com/dynatrace-oss/open-ecosystem-challenges/blob/main/LICENSE). + +By contributing, you agree that your contributions will be licensed under the same MIT License. + +--- + +## Propose an Adventure Idea + +Have a concept for a new challenge? We'd love to hear it! + +Adventure ideas are proposals for new challenges. You don't need to implement anything yet. Just describe what the +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 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. **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. + +### 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: + +| Quality | Description | +|---------------------|----------------------------------------------------------------------| +| **Action-oriented** | Focuses on what learners will *do*, not just what tools they'll use | +| **Story-driven** | Has an engaging narrative that motivates the challenges | +| **Progressive** | Multiple levels that build on each other (recommended, not required) | +| **Practical** | Teaches skills applicable to real-world scenarios | +| **Self-contained** | Can run entirely in a [devcontainer](https://containers.dev/) | + +### 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. + +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. + +**๐ŸŸก 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. + +#### 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 + +#### 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. + +Adventure 01 is a useful reference: Beginner introduces Argo CD ApplicationSets โ†’ Intermediate adds Argo Rollouts and PromQL โ†’ Expert adds OpenTelemetry Collector and distributed tracing. + +### Adventure Idea Template + +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 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. + +| Task (avoid) | Outcome (aim for) | +|---|---| +| Fix the ApplicationSet | See two distinct Applications in the Argo CD dashboard | +| Add instrumentation | Send traces to the OpenTelemetry Collector at `http://localhost:30107` | + +--- + +## Build a New Adventure + +Ready to turn an approved idea into a full adventure? This guide walks you through the implementation process. + +### Before You Start + +- **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](#propose-an-adventure-idea) โ€” 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 + +An adventure consists of: + +| Component | Purpose | +|-----------|---------| +| **Challenge files** | The "broken" state participants will fix | +| **Documentation** | Story, objectives, hints, and solution walkthroughs | +| **Devcontainer** | Pre-configured environment with all required infrastructure | +| **Verification script** | Validates solutions and generates completion certificate | + +### Adventure Structure + +Use `00` as the adventure number during development. When your adventure is scheduled for release, maintainers will assign the final number and move it out of `planned/`. + +``` +adventures/planned/00-adventure-name/ +โ”œโ”€โ”€ README.md # Brief intro + link to docs +โ”œโ”€โ”€ docs/ +โ”‚ โ”œโ”€โ”€ index.md # Adventure introduction +โ”‚ โ”œโ”€โ”€ beginner.md # Level guide +โ”‚ โ”œโ”€โ”€ intermediate.md +โ”‚ โ”œโ”€โ”€ expert.md +โ”‚ โ””โ”€โ”€ solutions/ +โ”‚ โ”œโ”€โ”€ beginner.md # Solution walkthrough +โ”‚ โ”œโ”€โ”€ intermediate.md +โ”‚ โ””โ”€โ”€ expert.md +โ”œโ”€โ”€ beginner/ +โ”‚ โ”œโ”€โ”€ verify.sh # Verification script +โ”‚ โ””โ”€โ”€ [challenge files] +โ”œโ”€โ”€ intermediate/ +โ”‚ โ””โ”€โ”€ ... +โ””โ”€โ”€ expert/ + โ””โ”€โ”€ ... + +.devcontainer/00-adventure-name_01-beginner/ +โ”œโ”€โ”€ devcontainer.json +โ”œโ”€โ”€ post-create.sh # Runs once (install tools) +โ””โ”€โ”€ post-start.sh # Runs every start (start services) +``` + +### Step-by-Step + +#### 1. Scaffold the Files + +Run the scaffolding script to generate the skeleton for your adventure level: + +```bash +make new-adventure +``` + +This will prompt you to select an adventure and level, then generate: + +- `adventures/planned/00-adventure-name/` โ€” adventure base with `README.md` and `docs/index.md` +- `adventures/planned/00-adventure-name/docs/.md` โ€” level guide +- `adventures/planned/00-adventure-name//verify.sh` โ€” verification script skeleton +- `.devcontainer/00-adventure-name_NN-level/` โ€” `devcontainer.json`, `post-create.sh`, `post-start.sh` + +Search for `TODO` in the generated files to find everything that needs filling in. + +#### 2. Configure the Devcontainer + +Open the generated `.devcontainer/00-adventure-name_NN-level/` files and fill in the TODOs. + +For Kubernetes-based adventures, [Adventure 01](adventures/01-echoes-lost-in-orbit/) is a good reference for what features and setup scripts to use. + +**post-create.sh** runs once when the container is created: +- Install CLI tools using setup scripts from `lib/` โ€” every script accepts a `--version` flag to pin a specific version. Run any script with `--help` to see available flags and defaults. +- Pull container images +- Set up one-time configurations + +Example calls in `post-create.sh`: +```bash +"$REPO_ROOT/lib/kubernetes/init.sh" # use default versions +"$REPO_ROOT/lib/argocd/init.sh" --version v3.5.0 # pin a version +"$REPO_ROOT/lib/argocd/init.sh" --read-only --version v3.5.0 # combine flags +"$REPO_ROOT/lib/kubernetes/init.sh" --kubectl-version v1.35.0 --helm-version v4.1.0 # per-tool versions +``` + +**post-start.sh** runs every time the container starts: +- Start services (databases, clusters, etc.) +- Apply initial state + +**Infrastructure constraints:** + +Codespaces run on 2 cores and 8 GB RAM by default. Design your adventure within these limits โ€” avoid memory-hungry workloads running in parallel and prefer lightweight images where possible. + +Post-create should finish in under 15 minutes, but aim for well under that. + +#### 3. Build the Working Solution + +Implement the fully working version first. This is what the solved challenge looks like where everything works correctly. + +This approach helps you: +- Understand the problem space before designing the challenge +- Ensure the challenge is actually solvable +- Have a reference implementation for the solution walkthrough + +#### 4. Introduce the Challenges + +Work backwards from your working solution to create the "broken" state participants will fix. + +Good challenges are: +- **Realistic.** Introduce issues that could happen in real-world scenarios. +- **Discoverable.** Problems should be findable using standard tools and techniques. +- **Focused.** Each issue should teach something from the learning objectives. +- **Solvable.** Don't require knowledge outside what's being taught. + +Not sure if a challenge belongs at Beginner, Intermediate, or Expert? See [Calibrating Difficulty](#calibrating-difficulty) for concrete signals and time expectations. + +#### 5. Write the Documentation + +Fill in the generated `docs/.md` โ€” it already contains the story, objectives, and learning outcomes from the idea file. Add: +- Architecture overview (how the level is set up) +- UI access instructions with port numbers +- Where to start investigating +- Helpful links to external docs + +No spoilers โ€” save those for a `solutions/.md` file. + +See [Adventure 01's beginner level](adventures/01-echoes-lost-in-orbit/docs/beginner.md) for a good example. + +#### 6. Create the Verification Script + +Fill in the generated `/verify.sh`. It already has the boilerplate wired up โ€” add your checks between the `print_sub_header` and the summary block. + +A good verification script: +- Passes when the challenge is solved correctly +- Fails with helpful error messages when not solved +- Generates a certificate users can copy to claim completion + +**Check outcomes, not implementation.** Verify the state the participant should have reached โ€” a service is healthy, traces are present in Jaeger, a metric is being collected โ€” not how they got there. File content checks (`check_file_contains`) are a last resort: they break for valid alternative solutions and reward copy-pasting over understanding. If your objective says "see traces in Jaeger", your verification should check that traces exist, not that a specific import was added. + +Browse `lib/scripts/` to see the available helper functions. + +#### 7. Final Test Run + +Before submitting: + +1. **Start fresh.** Open a new Codespace to test the full experience. +2. **Solve the challenge.** Complete it as a participant would. +3. **Run verification.** Ensure `verify.sh` passes when solved and fails when not. +4. **Check all links.** Documentation should be complete and accurate. + +### Tips + +- **[Open a draft PR early.](https://github.com/dynatrace-oss/open-ecosystem-challenges/compare)** Get feedback on structure before completing everything. +- **Ship one level at a time.** Each level gets its own PR โ€” start with one, get it working, then build the next. Use `Part of #` on all but the last PR, and `Closes #` on the final one so the tracking issue closes automatically. +- **Test on slow connections.** Codespace startup time matters. +- **Write clear error messages.** Help participants understand what went wrong without giving away the solution. + +--- + +## Write a Solution Walkthrough + +Solution walkthroughs help participants who get stuck and serve as learning resources for those who want to understand the "why" behind each solution. + +> โš ๏ธ **Walkthroughs are only accepted after the challenge deadline has passed.** This protects the experience for active participants. + +### How to Contribute + +Browse [walkthrough issues](https://github.com/dynatrace-oss/open-ecosystem-challenges/issues?q=is%3Aissue+is%3Aopen+label%3A%22solution+walkthrough%22), comment to claim a level, and [submit your walkthrough as a PR](https://github.com/dynatrace-oss/open-ecosystem-challenges/compare). Walkthroughs can take any form: + +- **External content** โ€” a blog post, video, or any public resource. Just link to it from the adventure's solutions page. +- **In-repo** โ€” a markdown file in `adventures/XX-adventure-name/docs/solutions/`. + +The most useful walkthroughs don't just show what to fix โ€” they explain *why* something was broken and how you'd reason your way to the solution. diff --git a/README.md b/README.md index 3ed8409b..a57e40f7 100644 --- a/README.md +++ b/README.md @@ -18,4 +18,4 @@ headaches. ## ๐Ÿš€ Ready to Start? -[Choose your adventure](https://dynatrace-oss.github.io/open-ecosystem-challenges/) and begin learning! +[Choose your adventure](https://offon.dev/adventures/) and begin learning! diff --git a/adventures/01-echoes-lost-in-orbit/README.md b/adventures/01-echoes-lost-in-orbit/README.md index 2a68cd6d..7f1cc850 100644 --- a/adventures/01-echoes-lost-in-orbit/README.md +++ b/adventures/01-echoes-lost-in-orbit/README.md @@ -10,4 +10,4 @@ ready to go. ## ๐Ÿš€ Ready to Start? -[Choose your level](https://dynatrace-oss.github.io/open-ecosystem-challenges/01-echoes-lost-in-orbit/) and begin learning! \ No newline at end of file +[Choose your level](https://offon.dev/adventures/echoes-lost-in-orbit/) and begin learning! \ No newline at end of file diff --git a/adventures/01-echoes-lost-in-orbit/beginner/smoke-test.sh b/adventures/01-echoes-lost-in-orbit/beginner/smoke-test.sh index 20804bc4..9e7841b9 100755 --- a/adventures/01-echoes-lost-in-orbit/beginner/smoke-test.sh +++ b/adventures/01-echoes-lost-in-orbit/beginner/smoke-test.sh @@ -13,7 +13,7 @@ OBJECTIVE="By the end of this level, you should: - Make the system resilient so Argo CD automatically reverts manual changes made to the cluster - Confirm that updates happen automatically without leaving stale resources behind" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/01-echoes-lost-in-orbit/beginner" +DOCS_URL="https://offon.dev/adventures/echoes-lost-in-orbit/levels/beginner" print_header \ 'Challenge 01: Echoes Lost in Orbit' \ diff --git a/adventures/01-echoes-lost-in-orbit/docs/index.md b/adventures/01-echoes-lost-in-orbit/docs/index.md index 61bdb398..e064883d 100644 --- a/adventures/01-echoes-lost-in-orbit/docs/index.md +++ b/adventures/01-echoes-lost-in-orbit/docs/index.md @@ -40,7 +40,7 @@ independent โ€” pick your level and start wherever you feel comfortable! The Echo Server is misbehaving. Both environments seem to be down, and messages are silent. Your mission: investigate the ArgoCD configuration and restore proper multi-environment delivery. -[**Start the Beginner Challenge**](./beginner.md){ .md-button .md-button--primary } +[**Start the Beginner Challenge**](./beginner.md) ### ๐ŸŸก Intermediate: The Silent Canary @@ -51,7 +51,7 @@ After fixing the communication outage, the Intergalactic Union welcomed a new sp team attempted to deploy their language files using a progressive delivery system, but the rollout is failing. Your mission: debug the broken canary deployment and bring the Zephyrians' voices online. -[**Start the Intermediate Challenge**](./intermediate.md){ .md-button .md-button--primary } +[**Start the Intermediate Challenge**](./intermediate.md) ### ๐Ÿ”ด Expert: Echoes in the Dark @@ -62,5 +62,5 @@ After fixing the Zephyrian communications, word of your progressive release mast They 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. Every millisecond of latency matters, and any error could strand travelers between dimensions. -[**Start the Expert Challenge**](./expert.md){ .md-button .md-button--primary } +[**Start the Expert Challenge**](./expert.md) diff --git a/adventures/01-echoes-lost-in-orbit/expert/smoke-test.sh b/adventures/01-echoes-lost-in-orbit/expert/smoke-test.sh index 834191a1..339ee7a7 100755 --- a/adventures/01-echoes-lost-in-orbit/expert/smoke-test.sh +++ b/adventures/01-echoes-lost-in-orbit/expert/smoke-test.sh @@ -17,7 +17,7 @@ OBJECTIVE="By the end of this level, you should have: - Error rate thresholds (< 5%) - Latency thresholds for the 95th percentile (< 1000ms)" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/01-echoes-lost-in-orbit/expert" +DOCS_URL="https://offon.dev/adventures/echoes-lost-in-orbit/levels/expert" print_header \ 'Challenge 01: Echoes Lost in Orbit' \ diff --git a/adventures/01-echoes-lost-in-orbit/intermediate/smoke-test.sh b/adventures/01-echoes-lost-in-orbit/intermediate/smoke-test.sh index d13f3060..0678f545 100755 --- a/adventures/01-echoes-lost-in-orbit/intermediate/smoke-test.sh +++ b/adventures/01-echoes-lost-in-orbit/intermediate/smoke-test.sh @@ -12,7 +12,7 @@ OBJECTIVE="By the end of this level, you should have: - Two working PromQL queries in the AnalysisTemplate that validate application health during releases - All rollouts complete successfully" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/01-echoes-lost-in-orbit/intermediate" +DOCS_URL="https://offon.dev/adventures/echoes-lost-in-orbit/levels/intermediate" print_header \ 'Challenge 01: Echoes Lost in Orbit' \ diff --git a/adventures/01-echoes-lost-in-orbit/mkdocs.yaml b/adventures/01-echoes-lost-in-orbit/mkdocs.yaml deleted file mode 100644 index 0794e527..00000000 --- a/adventures/01-echoes-lost-in-orbit/mkdocs.yaml +++ /dev/null @@ -1,11 +0,0 @@ -site_name: '๐Ÿ›ฐ๏ธ 01: Echoes Lost in Orbit' - -nav: - - Introduction: index.md - - '๐ŸŸข Beginner': beginner.md - - '๐ŸŸก Intermediate': intermediate.md - - '๐Ÿ”ด Expert': expert.md - - 'Solutions': - - '๐ŸŸข Beginner': solutions/beginner.md - - '๐ŸŸก Intermediate': solutions/intermediate.md - - '๐Ÿ”ด Expert': solutions/expert.md diff --git a/adventures/02-building-cloudhaven/README.md b/adventures/02-building-cloudhaven/README.md index ca88d61f..b900d5ff 100644 --- a/adventures/02-building-cloudhaven/README.md +++ b/adventures/02-building-cloudhaven/README.md @@ -9,4 +9,4 @@ The entire **infrastructure is pre-provisioned in your Codespace** โ€” OpenTofu ## ๐Ÿš€ Ready to Start? -[Choose your level](https://dynatrace-oss.github.io/open-ecosystem-challenges/02-building-cloudhaven/) and begin learning! \ No newline at end of file +[Choose your level](https://offon.dev/adventures/building-cloudhaven/) and begin learning! \ No newline at end of file diff --git a/adventures/02-building-cloudhaven/beginner/smoke-test.sh b/adventures/02-building-cloudhaven/beginner/smoke-test.sh index f1108b29..f347fdd3 100755 --- a/adventures/02-building-cloudhaven/beginner/smoke-test.sh +++ b/adventures/02-building-cloudhaven/beginner/smoke-test.sh @@ -13,7 +13,7 @@ OBJECTIVE="By the end of this level, you should: - Store state remotely in a GCS backend following best practices so the Guild can collaborate - Resolve all TODOs in the code and successfully run tofu apply" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/02-building-cloudhaven/beginner" +DOCS_URL="https://offon.dev/adventures/building-cloudhaven/levels/beginner" print_header \ 'Challenge 02: Building CloudHaven' \ diff --git a/adventures/02-building-cloudhaven/docs/beginner.md b/adventures/02-building-cloudhaven/docs/beginner.md index 6ceced83..6da3835b 100644 --- a/adventures/02-building-cloudhaven/docs/beginner.md +++ b/adventures/02-building-cloudhaven/docs/beginner.md @@ -53,7 +53,7 @@ Your Codespace comes pre-configured with the following tools to help you solve t Quick start: -- Fork the [repo](https://dynatrace-oss.github.io/open-ecosystem-challenges/) +- Fork the [repo](https://github.com/dynatrace-oss/open-ecosystem-challenges) - Create a Codespace - Select "๐ŸŒ† Adventure 02 | ๐ŸŸข Beginner (The Foundation Stones)" - Wait ~2 minutes for the environment to initialize (`Cmd/Ctrl + Shift + P` โ†’ `View Creation Log` to view progress) diff --git a/adventures/02-building-cloudhaven/docs/index.md b/adventures/02-building-cloudhaven/docs/index.md index bb29e9ac..3539f079 100644 --- a/adventures/02-building-cloudhaven/docs/index.md +++ b/adventures/02-building-cloudhaven/docs/index.md @@ -45,7 +45,7 @@ some services remain half-configured or misconfigured. Your mission: Complete the OpenTofu configuration and establish proper state management. -[**Start the Beginner Challenge**](./beginner.md){ .md-button .md-button--primary } +[**Start the Beginner Challenge**](./beginner.md) ### ๐ŸŸก Intermediate: The Modular Metropolis @@ -59,7 +59,7 @@ working tests... and buggy code that doesn't match them. Your mission: Fix the bugs, complete the integration test, and deploy the infrastructure. -[**Start the Intermediate Challenge**](./intermediate.md){ .md-button .md-button--primary } +[**Start the Intermediate Challenge**](./intermediate.md) ### ๐Ÿ”ด Expert: The Guardian Protocols @@ -70,4 +70,4 @@ CloudHaven needs automated guardians: workflows that detect infrastructure drift integration tests, and security scans, and then apply safe changes. A previous engineer started the setup but left it incomplete. Your mission: bring the Guardian Protocols online. -[**Start the Expert Challenge**](./expert.md){ .md-button .md-button--primary } +[**Start the Expert Challenge**](./expert.md) diff --git a/adventures/02-building-cloudhaven/expert/smoke-test.sh b/adventures/02-building-cloudhaven/expert/smoke-test.sh index ff190690..a4eaf0e5 100755 --- a/adventures/02-building-cloudhaven/expert/smoke-test.sh +++ b/adventures/02-building-cloudhaven/expert/smoke-test.sh @@ -12,7 +12,7 @@ OBJECTIVE="By the end of this level, your workflows should: - Validate pull requests (run plan, tests, security scans, comment on PR) - Apply infrastructure automatically when PR is merged" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/02-building-cloudhaven/expert" +DOCS_URL="https://offon.dev/adventures/building-cloudhaven/levels/expert" print_header \ 'Challenge 02: Building CloudHaven' \ diff --git a/adventures/02-building-cloudhaven/intermediate/smoke-test.sh b/adventures/02-building-cloudhaven/intermediate/smoke-test.sh index bf415bca..3e507843 100755 --- a/adventures/02-building-cloudhaven/intermediate/smoke-test.sh +++ b/adventures/02-building-cloudhaven/intermediate/smoke-test.sh @@ -12,7 +12,7 @@ OBJECTIVE="By the end of this level, you should have: - A completed integration test that applies infrastructure against the mock GCP API - Three districts deployed with correctly configured infrastructure (vaults and ledgers)" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/02-building-cloudhaven/intermediate" +DOCS_URL="https://offon.dev/adventures/building-cloudhaven/levels/intermediate" print_header \ 'Challenge 02: Building CloudHaven' \ diff --git a/adventures/02-building-cloudhaven/mkdocs.yaml b/adventures/02-building-cloudhaven/mkdocs.yaml deleted file mode 100644 index 522374d7..00000000 --- a/adventures/02-building-cloudhaven/mkdocs.yaml +++ /dev/null @@ -1,7 +0,0 @@ -site_name: '๐ŸŒ†๏ธ 02: Building CloudHaven' - -nav: - - Introduction: index.md - - '๐ŸŸข Beginner': beginner.md - - '๐ŸŸก Intermediate': intermediate.md - - '๐Ÿ”ด Expert': expert.md diff --git a/adventures/03-the-ai-observatory/README.md b/adventures/03-the-ai-observatory/README.md index b609d5e1..ea8e5fd6 100644 --- a/adventures/03-the-ai-observatory/README.md +++ b/adventures/03-the-ai-observatory/README.md @@ -10,5 +10,4 @@ are ready to go. ## ๐Ÿš€ Ready to Start? -[Choose your level](https://dynatrace-oss.github.io/open-ecosystem-challenges/03-the-ai-observatory/) and begin -learning! +[Choose your level](https://offon.dev/adventures/the-ai-observatory/) and begin learning! diff --git a/adventures/03-the-ai-observatory/beginner/verify.sh b/adventures/03-the-ai-observatory/beginner/verify.sh index 87cf516e..f9b6cc7b 100755 --- a/adventures/03-the-ai-observatory/beginner/verify.sh +++ b/adventures/03-the-ai-observatory/beginner/verify.sh @@ -13,7 +13,7 @@ OBJECTIVE="By the end of this level, you should: - See and analyze traces in Jaeger to find out what causes the high bandwidth usage - Provide the correct answer in quiz.txt" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/03-the-ai-observatory/beginner" +DOCS_URL="https://offon.dev/adventures/the-ai-observatory/levels/beginner" print_header \ 'Challenge 03: The AI Observatory' \ diff --git a/adventures/03-the-ai-observatory/docs/index.md b/adventures/03-the-ai-observatory/docs/index.md index 074145e4..5a630770 100644 --- a/adventures/03-the-ai-observatory/docs/index.md +++ b/adventures/03-the-ai-observatory/docs/index.md @@ -34,7 +34,7 @@ independent โ€” pick your level and start wherever you feel comfortable! The HubSystem is running "blind". Your mission: instrument the Python application with OpenLLMetry, send traces to the collector, and use Jaeger to find out what the AI is actually doing. -[**Start the Beginner Challenge**](./beginner.md){ .md-button .md-button--primary } +[**Start the Beginner Challenge**](./beginner.md) ### ๐ŸŸก Intermediate: The Distracted Pilot @@ -46,7 +46,7 @@ You've escaped aboard the Perihelion, a research vessel piloted by a very opinio coordinates to RaviHyral should have been ready an hour ago โ€” but ART is distracted. Your mission: instrument the RAG pipeline, track what ART is actually retrieving, and fix the navigation system before you miss the jump window. -[**Start the Intermediate Challenge**](./intermediate.md){ .md-button .md-button--primary } +[**Start the Intermediate Challenge**](./intermediate.md) ### ๐Ÿ”ด Expert: The Noise Filter @@ -59,5 +59,5 @@ mess. Non-standard span names, missing token usage, and Jaeger drowning in noise instrumentation to follow GenAI semantic conventions, record errors properly, and configure tail sampling to filter out the noise. -[**Start the Expert Challenge**](./expert.md){ .md-button .md-button--primary } +[**Start the Expert Challenge**](./expert.md) diff --git a/adventures/03-the-ai-observatory/expert/verify.sh b/adventures/03-the-ai-observatory/expert/verify.sh index dc0b86a3..25a18457 100755 --- a/adventures/03-the-ai-observatory/expert/verify.sh +++ b/adventures/03-the-ai-observatory/expert/verify.sh @@ -11,7 +11,7 @@ OBJECTIVE="By the end of this level, you should: - Fix ART's chat span to follow OpenTelemetry GenAI semantic conventions โ€” including token usage - Configure tail sampling in the OpenTelemetry Collector to only keep traces that contain errors or take longer than 5 seconds" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/03-the-ai-observatory/expert" +DOCS_URL="https://offon.dev/adventures/the-ai-observatory/levels/expert" print_header \ 'Challenge 03: The AI Observatory' \ diff --git a/adventures/03-the-ai-observatory/intermediate/verify.sh b/adventures/03-the-ai-observatory/intermediate/verify.sh index 9bc4a685..f93ec9e4 100755 --- a/adventures/03-the-ai-observatory/intermediate/verify.sh +++ b/adventures/03-the-ai-observatory/intermediate/verify.sh @@ -13,7 +13,7 @@ OBJECTIVE="By the end of this level, you should: - Create a Prometheus recording rule to calculate ART's 'Distraction Level' - Restore the navigation system so ART successfully calculates the jump coordinates to RaviHyral" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/03-the-ai-observatory/intermediate" +DOCS_URL="https://offon.dev/adventures/the-ai-observatory/levels/intermediate" print_header \ 'Challenge 03: The AI Observatory' \ diff --git a/adventures/03-the-ai-observatory/mkdocs.yaml b/adventures/03-the-ai-observatory/mkdocs.yaml deleted file mode 100644 index 15009898..00000000 --- a/adventures/03-the-ai-observatory/mkdocs.yaml +++ /dev/null @@ -1,7 +0,0 @@ -site_name: '๐Ÿ”ญ 03: The AI Observatory' - -nav: - - Introduction: index.md - - '๐ŸŸข Beginner': beginner.md - - '๐ŸŸก Intermediate': intermediate.md - - '๐Ÿ”ด Expert': expert.md diff --git a/adventures/04-blind-by-design/README.md b/adventures/04-blind-by-design/README.md index 9b80e3e7..b3837fdd 100644 --- a/adventures/04-blind-by-design/README.md +++ b/adventures/04-blind-by-design/README.md @@ -9,4 +9,4 @@ The entire **infrastructure is pre-provisioned in your Codespace**. ## ๐Ÿš€ Ready to Start? -[Choose your level](https://dynatrace-oss.github.io/open-ecosystem-challenges/04-blind-by-design/) and begin learning! +[Choose your level](https://offon.dev/adventures/blind-by-design/) and begin learning! diff --git a/adventures/04-blind-by-design/beginner/verify.sh b/adventures/04-blind-by-design/beginner/verify.sh index 84aa7d22..bdbb723c 100755 --- a/adventures/04-blind-by-design/beginner/verify.sh +++ b/adventures/04-blind-by-design/beginner/verify.sh @@ -12,7 +12,7 @@ OBJECTIVE="By the end of this level, you should: - Confirm the response payload includes the OpenFeature evaluation details โ€” flag key, variant, reason, value - Edit flags.json to change the defaultVariant, save, and have the next request return the new variant without restarting the app" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/04-blind-by-design/beginner" +DOCS_URL="https://offon.dev/adventures/blind-by-design/levels/beginner" APP_URL="http://localhost:8080/" FLAGS_FILE="$SCRIPT_DIR/flags.json" diff --git a/adventures/04-blind-by-design/expert/verify.sh b/adventures/04-blind-by-design/expert/verify.sh index faec4d0d..e44a1d6e 100755 --- a/adventures/04-blind-by-design/expert/verify.sh +++ b/adventures/04-blind-by-design/expert/verify.sh @@ -13,7 +13,7 @@ OBJECTIVE="By the end of this level, the lab hits each of these observable outco - The 'vision_amplifier_v2' rollout is rolled back to 100% off โ€” without redeploying the lab - HTTP 5xx rate over the last minute drops below 1%" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/04-blind-by-design/expert" +DOCS_URL="https://offon.dev/adventures/blind-by-design/levels/expert" print_header \ 'Adventure 04: Blind by Design' \ diff --git a/adventures/04-blind-by-design/intermediate/verify.sh b/adventures/04-blind-by-design/intermediate/verify.sh index d4be107b..f2a1c8e7 100755 --- a/adventures/04-blind-by-design/intermediate/verify.sh +++ b/adventures/04-blind-by-design/intermediate/verify.sh @@ -14,7 +14,7 @@ OBJECTIVE="By the end of this level, the lab hits each of these observable outco - Every evaluation produces an [AUDIT] log line carrying species, country, and dose - The response is never 'untreated' (provider is wired and reaches flagd)" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/04-blind-by-design/intermediate" +DOCS_URL="https://offon.dev/adventures/blind-by-design/levels/intermediate" print_header \ 'Adventure 04: Blind by Design' \ diff --git a/adventures/04-blind-by-design/mkdocs.yaml b/adventures/04-blind-by-design/mkdocs.yaml deleted file mode 100644 index fae87634..00000000 --- a/adventures/04-blind-by-design/mkdocs.yaml +++ /dev/null @@ -1,7 +0,0 @@ -site_name: '๐Ÿงช 04: Blind by Design' - -nav: - - Introduction: index.md - - '๐ŸŸข Beginner': beginner.md - - '๐ŸŸก Intermediate': intermediate.md - - '๐Ÿ”ด Expert': expert.md diff --git a/adventures/planned/00-lex-imperfecta/README.md b/adventures/planned/00-lex-imperfecta/README.md index f27ea873..1d48f125 100644 --- a/adventures/planned/00-lex-imperfecta/README.md +++ b/adventures/planned/00-lex-imperfecta/README.md @@ -12,5 +12,4 @@ The entire **infrastructure is pre-provisioned in your Codespace** ## ๐Ÿš€ Ready to Start? -[Choose your level](https://dynatrace-oss.github.io/open-ecosystem-challenges/00-lex-imperfecta/) and begin -learning! +[Choose your level](https://offon.dev/adventures/lex-imperfecta/) and begin learning! diff --git a/adventures/planned/00-lex-imperfecta/beginner/verify.sh b/adventures/planned/00-lex-imperfecta/beginner/verify.sh index 1a8a5f61..ccc21ddc 100755 --- a/adventures/planned/00-lex-imperfecta/beginner/verify.sh +++ b/adventures/planned/00-lex-imperfecta/beginner/verify.sh @@ -12,7 +12,7 @@ OBJECTIVE="By the end of this level, you should have: - All workloads running as privileged containers blocked at admission with a clear policy violation message - Confirmed that all other workloads deploy and run successfully in the cluster" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/00-lex-imperfecta/beginner" +DOCS_URL="https://offon.dev/adventures/lex-imperfecta/levels/beginner" print_header \ 'Challenge 00: Lex Imperfecta' \ diff --git a/adventures/planned/00-lex-imperfecta/docs/index.md b/adventures/planned/00-lex-imperfecta/docs/index.md index eac337b9..ee14e639 100644 --- a/adventures/planned/00-lex-imperfecta/docs/index.md +++ b/adventures/planned/00-lex-imperfecta/docs/index.md @@ -25,4 +25,4 @@ independent โ€” pick your level and start wherever you feel comfortable. Fix broken Kyverno policies to restore proper admission control. -[**Start the Beginner Challenge**](./beginner.md){ .md-button .md-button--primary } +[**Start the Beginner Challenge**](./beginner.md) diff --git a/adventures/planned/00-lex-imperfecta/mkdocs.yaml b/adventures/planned/00-lex-imperfecta/mkdocs.yaml deleted file mode 100644 index 275892ff..00000000 --- a/adventures/planned/00-lex-imperfecta/mkdocs.yaml +++ /dev/null @@ -1,5 +0,0 @@ -site_name: 'โš–๏ธ 00: Lex Imperfecta' - -nav: - - Introduction: index.md - - '๐ŸŸข Beginner': beginner.md diff --git a/docs/Challenge Assets/Blind By Design/Launch Annoucement.png b/docs/Challenge Assets/Blind By Design/Launch Annoucement.png deleted file mode 100644 index b81c1c23..00000000 Binary files a/docs/Challenge Assets/Blind By Design/Launch Annoucement.png and /dev/null differ diff --git a/docs/Challenge Assets/Blind By Design/Learning Value.png b/docs/Challenge Assets/Blind By Design/Learning Value.png deleted file mode 100644 index 10717ca9..00000000 Binary files a/docs/Challenge Assets/Blind By Design/Learning Value.png and /dev/null differ diff --git a/docs/Challenge Assets/Blind By Design/Reminder Graphic.png b/docs/Challenge Assets/Blind By Design/Reminder Graphic.png deleted file mode 100644 index ba5ee6ee..00000000 Binary files a/docs/Challenge Assets/Blind By Design/Reminder Graphic.png and /dev/null differ diff --git a/docs/Challenge Assets/Blind By Design/Share Graphic.png b/docs/Challenge Assets/Blind By Design/Share Graphic.png deleted file mode 100644 index ce9d3b06..00000000 Binary files a/docs/Challenge Assets/Blind By Design/Share Graphic.png and /dev/null differ diff --git a/docs/contributing/adventure-ideas.md b/docs/contributing/adventure-ideas.md deleted file mode 100644 index c1f60a24..00000000 --- a/docs/contributing/adventure-ideas.md +++ /dev/null @@ -1,110 +0,0 @@ -# Propose an Adventure Idea - -Have a concept for a new challenge? We'd love to hear it! - -Adventure ideas are proposals for new challenges. You don't need to implement anything yet. Just describe what the -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 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. **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. - -## 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: - -| Quality | Description | -|---------------------|----------------------------------------------------------------------| -| **Action-oriented** | Focuses on what learners will *do*, not just what tools they'll use | -| **Story-driven** | Has an engaging narrative that motivates the challenges | -| **Progressive** | Multiple levels that build on each other (recommended, not required) | -| **Practical** | Teaches skills applicable to real-world scenarios | -| **Self-contained** | Can run entirely in a [devcontainer](https://containers.dev/) | - -## 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. - -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. - -**๐ŸŸก 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. - -### 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 - -### 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. - -Adventure 01 is a useful reference: Beginner introduces Argo CD ApplicationSets โ†’ Intermediate adds Argo Rollouts and PromQL โ†’ Expert adds OpenTelemetry Collector and distributed tracing. - -## Adventure Idea Template - -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 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. - -| Task (avoid) | Outcome (aim for) | -|---|---| -| Fix the ApplicationSet | See two distinct Applications in the Argo CD dashboard | -| Add instrumentation | Send traces to the OpenTelemetry Collector at `http://localhost:30107` | - diff --git a/docs/contributing/adventures.md b/docs/contributing/adventures.md deleted file mode 100755 index f5e0a5d8..00000000 --- a/docs/contributing/adventures.md +++ /dev/null @@ -1,162 +0,0 @@ -# Build a New Adventure - -Ready to turn an approved idea into a full adventure? This guide walks you through the implementation process. - -## Before You Start - -- **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 - -An adventure consists of: - -| Component | Purpose | -|-----------|---------| -| **Challenge files** | The "broken" state participants will fix | -| **Documentation** | Story, objectives, hints, and solution walkthroughs | -| **Devcontainer** | Pre-configured environment with all required infrastructure | -| **Verification script** | Validates solutions and generates completion certificate | - -## Adventure Structure - -Use `00` as the adventure number during development. When your adventure is scheduled for release, maintainers will assign the final number and move it out of `planned/`. - -``` -adventures/planned/00-adventure-name/ -โ”œโ”€โ”€ README.md # Brief intro + link to docs -โ”œโ”€โ”€ mkdocs.yaml # Navigation for this adventure -โ”œโ”€โ”€ docs/ -โ”‚ โ”œโ”€โ”€ index.md # Adventure introduction -โ”‚ โ”œโ”€โ”€ beginner.md # Level guide -โ”‚ โ”œโ”€โ”€ intermediate.md -โ”‚ โ”œโ”€โ”€ expert.md -โ”‚ โ””โ”€โ”€ solutions/ -โ”‚ โ”œโ”€โ”€ beginner.md # Solution walkthrough -โ”‚ โ”œโ”€โ”€ intermediate.md -โ”‚ โ””โ”€โ”€ expert.md -โ”œโ”€โ”€ beginner/ -โ”‚ โ”œโ”€โ”€ verify.sh # Verification script -โ”‚ โ””โ”€โ”€ [challenge files] -โ”œโ”€โ”€ intermediate/ -โ”‚ โ””โ”€โ”€ ... -โ””โ”€โ”€ expert/ - โ””โ”€โ”€ ... - -.devcontainer/00-adventure-name_01-beginner/ -โ”œโ”€โ”€ devcontainer.json -โ”œโ”€โ”€ post-create.sh # Runs once (install tools) -โ””โ”€โ”€ post-start.sh # Runs every start (start services) -``` - -## Step-by-Step - -### 1. Scaffold the Files - -Run the scaffolding script to generate the skeleton for your adventure level: - -```bash -make new-adventure -``` - -This will prompt you to select an adventure and level, then generate: - -- `adventures/planned/00-adventure-name/` โ€” adventure base with `README.md`, `mkdocs.yaml`, and `docs/index.md` -- `adventures/planned/00-adventure-name/docs/.md` โ€” level guide -- `adventures/planned/00-adventure-name//verify.sh` โ€” verification script skeleton -- `.devcontainer/00-adventure-name_NN-level/` โ€” `devcontainer.json`, `post-create.sh`, `post-start.sh` - -Search for `TODO` in the generated files to find everything that needs filling in. - -### 2. Configure the Devcontainer - -Open the generated `.devcontainer/00-adventure-name_NN-level/` files and fill in the TODOs. - -For Kubernetes-based adventures, [Adventure 01](../../adventures/01-echoes-lost-in-orbit/) is a good reference for what features and setup scripts to use. - -**post-create.sh** runs once when the container is created: -- Install CLI tools using setup scripts from `lib/` โ€” every script accepts a `--version` flag to pin a specific version. Run any script with `--help` to see available flags and defaults. -- Pull container images -- Set up one-time configurations - -Example calls in `post-create.sh`: -```bash -"$REPO_ROOT/lib/kubernetes/init.sh" # use default versions -"$REPO_ROOT/lib/argocd/init.sh" --version v3.5.0 # pin a version -"$REPO_ROOT/lib/argocd/init.sh" --read-only --version v3.5.0 # combine flags -"$REPO_ROOT/lib/kubernetes/init.sh" --kubectl-version v1.35.0 --helm-version v4.1.0 # per-tool versions -``` - -**post-start.sh** runs every time the container starts: -- Start services (databases, clusters, etc.) -- Apply initial state - -**Infrastructure constraints:** - -Codespaces run on 2 cores and 8 GB RAM by default. Design your adventure within these limits โ€” avoid memory-hungry workloads running in parallel and prefer lightweight images where possible. - -Post-create should finish in under 15 minutes, but aim for well under that. - -### 3. Build the Working Solution - -Implement the fully working version first. This is what the solved challenge looks like where everything works correctly. - -This approach helps you: -- Understand the problem space before designing the challenge -- Ensure the challenge is actually solvable -- Have a reference implementation for the solution walkthrough - -### 4. Introduce the Challenges - -Work backwards from your working solution to create the "broken" state participants will fix. - -Good challenges are: -- **Realistic.** Introduce issues that could happen in real-world scenarios. -- **Discoverable.** Problems should be findable using standard tools and techniques. -- **Focused.** Each issue should teach something from the learning objectives. -- **Solvable.** Don't require knowledge outside what's being taught. - -Not sure if a challenge belongs at Beginner, Intermediate, or Expert? See [Calibrating Difficulty](adventure-ideas.md#calibrating-difficulty) for concrete signals and time expectations. - -### 5. Write the Documentation - -Fill in the generated `docs/.md` โ€” it already contains the story, objectives, and learning outcomes from the idea file. Add: -- Architecture overview (how the level is set up) -- UI access instructions with port numbers -- Where to start investigating -- Helpful links to external docs - -No spoilers โ€” save those for a `solutions/.md` file. - -See [Adventure 01's beginner level](../../adventures/01-echoes-lost-in-orbit/docs/beginner.md) for a good example. - -### 6. Create the Verification Script - -Fill in the generated `/verify.sh`. It already has the boilerplate wired up โ€” add your checks between the `print_sub_header` and the summary block. - -A good verification script: -- Passes when the challenge is solved correctly -- Fails with helpful error messages when not solved -- Generates a certificate users can copy to claim completion - -**Check outcomes, not implementation.** Verify the state the participant should have reached โ€” a service is healthy, traces are present in Jaeger, a metric is being collected โ€” not how they got there. File content checks (`check_file_contains`) are a last resort: they break for valid alternative solutions and reward copy-pasting over understanding. If your objective says "see traces in Jaeger", your verification should check that traces exist, not that a specific import was added. - -Browse `lib/scripts/` to see the available helper functions. - -### 7. Final Test Run - -Before submitting: - -1. **Start fresh.** Open a new Codespace to test the full experience. -2. **Solve the challenge.** Complete it as a participant would. -3. **Run verification.** Ensure `verify.sh` passes when solved and fails when not. -4. **Check all links.** Documentation should be complete and accurate. - -## Tips - -- **[Open a draft PR early.](https://github.com/dynatrace-oss/open-ecosystem-challenges/compare)** Get feedback on structure before completing everything. -- **Ship one level at a time.** Each level gets its own PR โ€” start with one, get it working, then build the next. Use `Part of #` on all but the last PR, and `Closes #` on the final one so the tracking issue closes automatically. -- **Test on slow connections.** Codespace startup time matters. -- **Write clear error messages.** Help participants understand what went wrong without giving away the solution. diff --git a/docs/contributing/index.md b/docs/contributing/index.md deleted file mode 100644 index 474bf4de..00000000 --- a/docs/contributing/index.md +++ /dev/null @@ -1,90 +0,0 @@ -# Contributing Guide - -Thank you for your interest in contributing to Open Ecosystem Challenges! - -Whether you're fixing a typo, proposing an adventure idea, or building an entire challenge, your contribution matters. - -## Ways to Contribute - -| Type | Description | Guide | -|-------------------------------|----------------------------------------------------------------|-----------------------------------------------------| -| โœจ Improvements & Bug Fixes | Improve docs, enhance challenge setup, fix bugs | This page | -| ๐Ÿ’ก Adventure Ideas | Propose a new adventure with a full implementation plan | [Adventure Ideas](adventure-ideas.md) | -| ๐Ÿ—๏ธ New Adventures | Build and implement a full adventure based on an approved idea | [Building Adventures](adventures.md) | -| ๐Ÿ“– Solution Walkthroughs | Write a step-by-step guide for a completed challenge | [Solution Walkthroughs](solution-walkthroughs.md) | - -## Code of Conduct - -This project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). Be respectful and constructive. - -## Before You Start - -1. **Check existing issues.** Search [open issues](https://github.com/dynatrace-oss/open-ecosystem-challenges/issues) before creating a new one. -2. **Determine if you need an issue:** - - **Small fixes** (typos, broken links): No issue needed, just open a PR. - - **Larger improvements & bug fixes**: Open an issue first to discuss. - - **Adventure ideas**: No issue needed, submit your idea directly as a PR. - - **New adventures & solution walkthroughs**: Pick up an existing issue. -3. **Claim the issue.** If working on an existing issue, comment to let others know you're on it. - -## Local Development Setup - -There are two paths depending on what you're working on: - -**Working on an adventure?** Use the adventure's devcontainer in GitHub Codespaces. It spins up all required infrastructure (Kubernetes, databases, etc.) automatically. See [Building Adventures](adventures.md) for details. - -**Everything else?** Use the default devcontainer. You can run it in [GitHub Codespaces](https://docs.github.com/en/codespaces) or [locally in VS Code](https://code.visualstudio.com/docs/devcontainers/containers). - -### Running the Documentation - -In the default devcontainer, dependencies are pre-installed. Just run: - -```bash -mkdocs serve -``` - -The docs site will be available at `http://localhost:8000`. - -## Pull Request Process - -1. **Fork the repository** and create your branch from `main`. -2. **Make your changes** with clear, focused commits. -3. **Test your changes.** Run verification scripts if applicable. -4. **Open a pull request** with a clear description of what you changed and why. -5. **Address feedback.** Maintainers will review and may request changes. - -Keep PRs focused. Smaller, single-purpose PRs are easier to review and merge. - -## Developer Certificate of Origin (DCO) - -This project uses the [Developer Certificate of Origin](https://developercertificate.org/) (DCO). All commits must be signed off to certify that you have the right to submit the code and agree to the DCO terms. - -Sign off your commits by adding `-s` to your commit command: - -```bash -git commit -s -m "Your commit message" -``` - -If you've already made commits without signing off, you can amend them: - -```bash -git commit --amend -s --no-edit -git push --force-with-lease -``` - -The DCO is enforced automatically via [cncf/dco2](https://github.com/cncf/dco2). PRs without signed-off commits will be flagged. - -## Getting Help - -- **Ideas & bugs?** [Open an issue](https://github.com/dynatrace-oss/open-ecosystem-challenges/issues) -- **Questions & discussions?** [Open Ecosystem Community](https://community.open-ecosystem.com/c/challenges) - -## License - -This project is licensed under the [MIT License](https://github.com/dynatrace-oss/open-ecosystem-challenges/blob/main/LICENSE). - -By contributing, you agree that your contributions will be licensed under the same MIT License. - -## Thank You - -Every contribution helps make these challenges better for the community. We appreciate your time and effort! \ No newline at end of file diff --git a/docs/contributing/solution-walkthroughs.md b/docs/contributing/solution-walkthroughs.md deleted file mode 100644 index 59bc6b3a..00000000 --- a/docs/contributing/solution-walkthroughs.md +++ /dev/null @@ -1,14 +0,0 @@ -# Write a Solution Walkthrough - -Solution walkthroughs help participants who get stuck and serve as learning resources for those who want to understand the "why" behind each solution. - -> โš ๏ธ **Walkthroughs are only accepted after the challenge deadline has passed.** This protects the experience for active participants. - -## How to Contribute - -Browse [walkthrough issues](https://github.com/dynatrace-oss/open-ecosystem-challenges/issues?q=is%3Aissue+is%3Aopen+label%3A%22solution+walkthrough%22), comment to claim a level, and [submit your walkthrough as a PR](https://github.com/dynatrace-oss/open-ecosystem-challenges/compare). Walkthroughs can take any form: - -- **External content** โ€” a blog post, video, or any public resource. Just link to it from the adventure's solutions page. -- **In-repo** โ€” a markdown file in `adventures/XX-adventure-name/docs/solutions/`. - -The most useful walkthroughs don't just show what to fix โ€” they explain *why* something was broken and how you'd reason your way to the solution. \ No newline at end of file diff --git a/docs/images/codespace-options.png b/docs/images/codespace-options.png deleted file mode 100644 index ebd09889..00000000 Binary files a/docs/images/codespace-options.png and /dev/null differ diff --git a/docs/images/new-codespace.png b/docs/images/new-codespace.png deleted file mode 100644 index 3abcc888..00000000 Binary files a/docs/images/new-codespace.png and /dev/null differ diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 8eeba39f..00000000 --- a/docs/index.md +++ /dev/null @@ -1,109 +0,0 @@ -# Open Ecosystem Challenges - -Welcome to Open Ecosystem Challenges! ๐Ÿš€ - -These are **hands-on, recurring prompts** designed to help you practice **Cloud Native, OpenTelemetry, AI/ML**, and -other **open source skills**. - -Each challenge runs in a **pre-provisioned environment**, so you can focus on solving real problems, not setup -headaches. - -**What makes these challenges special:** - -- ๐ŸŽฏ **Skill-focused** - Target specific technologies with clear objectives -- ๐Ÿ“– **Story-driven** - Learn through engaging narratives -- ๐Ÿš€ **Zero setup** - Run in GitHub Codespaces, pre-configured and ready -- โœ… **Two-step verification** - [Smoke tests and GitHub Actions](verification.md) validate your solution -- ๐ŸŽ“ **Three levels** - Beginner, Intermediate, and Expert for each adventure - -## ๐Ÿ—บ๏ธ Available Adventures - -Browse the available adventures and pick one that interests you: - -### May 2026: [Blind by Design](04-blind-by-design/index.md) - -**Story:** The Aletheia Institute's lab has been recording every subject as "untreated" for eight months โ€” the OpenFeature integration was never finished. Wire the SDK, read the chart by cohort, and roll back a misbehaving Phase 3 trial before the next enrollment batch is signed off. - -| Level | Name | ๐Ÿง  Key Learnings | -|-----------------|---------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| ๐ŸŸข Beginner | [Stand up the lab](04-blind-by-design/beginner.md) |
  • Wire the [OpenFeature](https://openfeature.dev/) Java SDK into a Spring Boot service
  • Configure [flagd](https://flagd.dev/) as a gRPC sidecar provider
  • Hot-reload flag definitions from `flags.json` without redeploying
| -| ๐ŸŸก Intermediate | [Outcome by cohort](04-blind-by-design/intermediate.md) |
  • OpenFeature targeting rules and evaluation context
  • Transaction context and Spring `HandlerInterceptor`
  • Audit hooks for per-cohort outcome tracking
| -| ๐Ÿ”ด Expert | [Read the chart](04-blind-by-design/expert.md) |
  • OpenTelemetry traces and metrics with OpenFeature hooks
  • Custom `ContextSpanHook` for eval context on Tempo spans
  • Fractional rollout detection and rollback via [Grafana LGTM](https://grafana.com/)
| - -### February 2026: [The AI Observatory](03-the-ai-observatory/index.md) - -**Story:** Investigate a mysterious bandwidth anomaly at a remote research station by instrumenting its AI system with OpenTelemetry. - -| Level | Name | ๐Ÿง  Key Learnings | -|-----------------|---------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| ๐ŸŸข Beginner | [Calibrating the Lens](03-the-ai-observatory/beginner.md) |
  • Instrument Python AI apps with [OpenLLMetry](https://github.com/traceloop/openllmetry)
  • Analyze traces in [Jaeger](https://www.jaegertracing.io/)
| -| ๐ŸŸก Intermediate | [The Distracted Pilot](03-the-ai-observatory/intermediate.md) |
  • Instrument RAG pipelines with [OpenLLMetry](https://github.com/traceloop/openllmetry)
  • Create custom [OpenTelemetry](https://opentelemetry.io/) metrics in Python
  • Write PromQL queries & recording rules in [Prometheus](https://prometheus.io/)
| -| ๐Ÿ”ด Expert | [The Noise Filter](03-the-ai-observatory/expert.md) |
  • OpenTelemetry GenAI semantic conventions
  • Tail sampling in the [OTel Collector](https://opentelemetry.io/docs/collector/)
| - -### January 2026: [Building CloudHaven](02-building-cloudhaven/index.md) - -**Story:** Join the Infrastructure Guild and modernize CloudHaven's infrastructure from manual provisioning to a -self-service platform using Infrastructure as Code. - -| Level | Name | ๐Ÿง  Key Learnings | -|-----------------|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| -| ๐ŸŸข Beginner | The Foundation Stones |
  • Infrastructure as Code with OpenTofu
  • Remote state management with GCS backend
  • Dynamic & conditional resources
| -| ๐ŸŸก Intermediate | The Modular Metropolis |
  • OpenTofu module testing with `tofu test`
  • Test-Driven Development (TDD) workflow
  • Input validation with regex
| -| ๐Ÿ”ด Expert | The Guardian Protocols |
  • GitHub Actions for drift detection and plan/apply
  • Integration tests with service containers
  • Security scanning with Trivy
| - -### December 2025: [Echoes Lost in Orbit](01-echoes-lost-in-orbit/index.md) - -**Story:** Restore interstellar communications by fixing broken GitOps setups, progressive delivery systems, and -observability pipelines across three galactic missions. - -| Level | Name | ๐Ÿง  Key Learnings | -|-----------------|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| ๐ŸŸข Beginner | Broken Echoes |
  • Debug GitOps flows with Argo CD
  • ApplicationSet templating & pitfalls
  • Environment isolation & namespaces
  • Sync policies: automated, prune & self-heal
| -| ๐ŸŸก Intermediate | The Silent Canary |
  • Progressive delivery with Argo Rollouts
  • Canary deployments & automated analysis
  • Write PromQL queries for health validation
  • Kube-state-metrics for deployment decisions
| -| ๐Ÿ”ด Expert | Hyperspace Operations & Transport |
  • Configure OpenTelemetry Collector pipelines
  • Spanmetrics connector (traces โ†’ metrics)
  • Detect "idle canaries" with traffic validation
  • Distributed tracing with Jaeger
  • Trace-derived metrics for progressive delivery
| - -More adventures coming soon! - -## ๐ŸŽฎ How It Works - -**Each level is independent** - start anywhere, complete in any order. Levels share a connected story but have their -own: - -- Codespace configuration -- Documentation and guides -- Validation tests - -**Levels:** - -- ๐ŸŸข **Beginner**: New to the technology? Start here to learn the basics -- ๐ŸŸก **Intermediate**: Comfortable with fundamentals? Practice advanced patterns -- ๐Ÿ”ด **Expert**: Want a real challenge? Tackle complex real-world scenarios - -## โœ… How to Verify Your Solution - -Each challenge includes a two-step verification process: - -1. **Smoke Test** - Run locally in your Codespace for quick validation -2. **GitHub Actions Workflow** - Comprehensive verification you manually trigger after pushing - -> ๐Ÿ“– **Learn more:** Read the complete [Verification Guide](verification.md) for detailed instructions on both steps. - -## โ“ FAQ - -**Do I need to complete levels in order?** -No! Each level is independent. Start wherever you feel comfortable. - -**Can I use these for team training?** -Absolutely! Perfect for upskilling, onboarding, internal training, and hackathons. - -**Are there costs?** -GitHub Codespaces offers free hours per month - usually sufficient for individual use. -Check [GitHub's pricing](https://github.com/features/codespaces) for details. - -**Need help?** -Check adventure-specific docs, [open an issue](https://github.com/dynatrace-oss/open-ecosystem-challenges/issues), or -start a [discussion](https://community.open-ecosystem.com/c/challenges). - -## ๐Ÿš€ Ready to Start? - -[Choose your adventure](#available-adventures) and begin learning! diff --git a/docs/start-a-challenge.md b/docs/start-a-challenge.md deleted file mode 100644 index 7d78198d..00000000 --- a/docs/start-a-challenge.md +++ /dev/null @@ -1,41 +0,0 @@ -# Start a Challenge - -The setup process is the same for all challenges. Fork -the [Open Ecosystem Challenges repository](https://github.com/dynatrace-oss/open-ecosystem-challenges), start a -Codespace with -your challenge's configuration, and wait for the infrastructure to deploy. - -## 1. Fork the Repository - -Click the **Fork** button in the top-right corner of the GitHub repo or -use [this link](https://github.com/dynatrace-oss/open-ecosystem-challenges/fork). - -### Already Have a Fork? - -If you've completed a previous challenge and already have a fork, sync it first to get the latest updates: - -1. Go to your fork on GitHub -2. Click **Sync fork** (above the file list) -3. Click **Update branch** if changes are available - -This ensures you have the latest challenge content before starting a new level. - -## 2. Start a Codespace - -- From your fork, click the green **Code** button โ†’ **Codespaces hamburger menu** โ†’ **New with options** - ![Create a new Codespace](./images/new-codespace.png) -- Select the configuration that matches your challenge (e.g., "Adventure 01 | ๐ŸŸข Beginner (Broken Echoes)" for the - beginner level of adventure 1) - ![Codespace options](./images/codespace-options.png) - -> โš ๏ธ **Important:** The challenge will not work if you choose a configuration that does not match your challenge (or the -> default). -## 3. Wait for Infrastructure to Deploy - -Your Codespace will automatically provision all necessary challenge infrastructure. This usually takes around 5-10 -minutes. - -> ๐Ÿ’ก **Tip:** To check the progress press `Cmd + Shift + P` (or `Ctrl + Shift + P` on Windows/Linux) and search for -`View Creation Log` (available after a few moments once the Codespace has initialized). - -Once complete, return to your specific challenge documentation for level-specific instructions on solving the challenge. diff --git a/docs/verification.md b/docs/verification.md deleted file mode 100644 index d527df93..00000000 --- a/docs/verification.md +++ /dev/null @@ -1,165 +0,0 @@ -# Verify Your Solution - -Each challenge includes a three-step verification process to help you validate and share your solution: - -1. **Local Smoke Test** - Quick validation in your Codespace -2. **Full Verification Workflow** - Comprehensive validation via GitHub Actions -3. **Submit Your Results** - Share your success with the community - -This process is designed to give you confidence in your solution without directly revealing the answers. - -## ๐Ÿงช Step 1: Local Smoke Test - -The smoke test is a script that runs directly in your Codespace to check basic success criteria. - -### What It Checks - -- โœ… Basic functionality (e.g., services are reachable) -- โœ… Key resources are deployed correctly -- โœ… Essential configuration is in place - -### What It Doesn't Check - -The smoke test deliberately avoids checking certain criteria to prevent revealing the solution. These more complex -validations are performed by the full verification workflow. - -### How to Run - -Each challenge level has its own smoke test script. Run it from the repository root: - -```bash -adventures///smoke-test.sh -``` - -**Example for Adventure 01, Beginner level:** - -```bash -adventures/01-echoes-lost-in-orbit/easy/smoke-test.sh -``` - -### Understanding the Results - -โœ… **If the smoke test passes:** - -- Your solution likely meets all requirements -- Proceed to Step 2 for full verification - -โŒ **If the smoke test fails:** - -- Review the error messages and hints provided -- Check your solution against the challenge objectives -- Make adjustments and run the test again - -## ๐Ÿ”„ Step 2: Full Verification Workflow - -The full verification workflow runs on GitHub Actions and performs comprehensive validation of your solution. - -### Prerequisites - -#### Enable GitHub Actions in Your Fork - -If this is a **new fork**, GitHub Actions workflows are disabled by default. You need to enable them: - -1. Go to your fork on GitHub -2. Click the **Actions** tab -3. Click the green button **"I understand my workflows, go ahead and enable them"** - -> ๐Ÿ’ก **Note:** This is a one-time setup for your fork. Once enabled, workflows will be available for all challenges. - -### Running the Verification Workflow - -The verification workflow validates more complex success criteria that cannot be checked locally without revealing the -solution. - -#### When to Run - -Run the verification workflow **after** your smoke test passes. - -#### How to Run - -1. **Commit and push your changes** to the `main` branch of your fork: - ```bash - git add . - git commit -m "Solved Adventure 01 - Easy level" - git push origin main - ``` - -2. **Manually trigger the workflow** on GitHub: - - Go to your fork on GitHub - - Click the **Actions** tab - - Select the **"Verify Adventure"** workflow from the left sidebar - - Click the **"Run workflow"** dropdown button - - Select the challenge you want to verify (e.g., `Adventure 01 | ๐ŸŸข Easy (Broken Echoes)`) - - Click **"Run workflow"** - -3. **Wait for the workflow to complete** - -### Understanding the Results - -โœ… **If the workflow passes:** - -- ๐ŸŽ‰ Congratulations! You've successfully completed the challenge! -- Proceed to Step 3 to claim your completion - -โŒ **If the workflow fails:** - -- Click on the failed workflow run to see detailed logs -- Review what criteria were not met -- Adjust your solution and try again -- Don't hesitate to [open a discussion](https://community.open-ecosystem.com/c/challenges) if you're stuck - -## ๐Ÿ“ธ Step 3: Submit Your Results - -Once your verification workflow passes, it's time to share your success with the community! - -### How to Submit - -1. **Take a screenshot** of your successful workflow run on GitHub Actions - - The screenshot should show the green checkmark and "Success" status - - Include the workflow name and your GitHub username in the screenshot - -2. **Post your screenshot** as a comment to the original challenge thread - - Find the discussion thread for your specific adventure and level - - Add a comment with your screenshot - - Optionally, share any interesting learnings or challenges you faced ๐Ÿ™Œ - -3. **Celebrate!** ๐ŸŽ‰ - - You've officially completed the challenge - - Your contribution is now part of the Open Ecosystem community - - Ready for more? Move on to the next level or choose another adventure! - -### Why Submit? - -- **Recognition**: Get acknowledged by the community for your achievement -- **Inspiration**: Help motivate others who are working on the same challenge -- **Community**: Connect with fellow learners and share insights -- **Progress Tracking**: Keep a record of your completed challenges - -## ๐ŸŽฏ Tips for Success - -- **Read the challenge objectives carefully**: They outline exactly what needs to be achieved -- **Run the smoke test before committing**: It provides fast feedback during development -- **Check the workflow logs**: They contain valuable debugging information if verification fails -- **Don't give up**: These challenges are designed to be... challenging! Learning happens through iteration - -## ๐Ÿค Need Help? - -If you're stuck or have questions about verification: - -- ๐Ÿ’ฌ [Start a discussion](https://community.open-ecosystem.com/c/challenges) -- ๐Ÿ› [Report an issue](https://github.com/dynatrace-oss/open-ecosystem-challenges/issues) if you think something is - broken -- ๐Ÿ“– Check the adventure-specific documentation for hints and resources - -## ๐Ÿ”’ Why This Verification Process? - -The three-step approach balances learning, validation, and community engagement: - -- **Smoke tests** give you fast, local feedback without an internet connection -- **Workflow verification** ensures comprehensive validation without giving away solutions in the local scripts -- **Community submission** celebrates your achievement and contributes to the learning ecosystem - -Together, they provide confidence that your solution is correct while preserving the learning experience - -Happy solving! ๐Ÿš€ - diff --git a/lib/scripts/output.sh b/lib/scripts/output.sh index cfbb57c3..223293b3 100644 --- a/lib/scripts/output.sh +++ b/lib/scripts/output.sh @@ -110,7 +110,7 @@ print_test_summary() { print_info_indent "3. Manually trigger the 'Verify Adventure' workflow on GitHub Actions" print_info_indent "4. Once verified, share your success with the community! ๐ŸŽ‰" print_new_line - print_info "๐Ÿ“– For detailed verification instructions, see: https://dynatrace-oss.github.io/open-ecosystem-challenges/verification/" + print_info "๐Ÿ“– For detailed verification instructions, see: https://offon.dev/adventures/" exit fi diff --git a/mkdocs.yaml b/mkdocs.yaml deleted file mode 100644 index eeaaead3..00000000 --- a/mkdocs.yaml +++ /dev/null @@ -1,52 +0,0 @@ -site_name: "Open Ecosystem Challenges" -repo_name: "View on GitHub" -repo_url: "https://github.com/dynatrace-oss/open-ecosystem-challenges" -docs_dir: docs -nav: - - 'Overview': index.md - - 'How to Play': - - start-a-challenge.md - - verification.md - - 'Adventures': '*include ./adventures/*/mkdocs.yaml' - - 'Contributing': - - contributing/index.md - - contributing/adventure-ideas.md - - contributing/adventures.md - - contributing/solution-walkthroughs.md -plugins: - - monorepo - - search -theme: - name: material - features: - - content.code.copy - palette: - # Palette toggle for automatic mode - - media: "(prefers-color-scheme)" - toggle: - icon: material/brightness-auto - name: Switch to light mode - - # Palette toggle for light mode - - media: "(prefers-color-scheme: light)" - scheme: default - toggle: - icon: material/brightness-7 - name: Switch to dark mode - - # Palette toggle for dark mode - - media: "(prefers-color-scheme: dark)" - scheme: slate - toggle: - icon: material/brightness-4 - name: Switch to system preference -markdown_extensions: -- attr_list -- toc: - permalink: '#' -- md_in_html -- admonition -- pymdownx.details -- pymdownx.superfences -- pymdownx.snippets: - base_path: ["docs"] diff --git a/scripts/new-adventure.sh b/scripts/new-adventure.sh index a1f78b56..cb3ffb51 100755 --- a/scripts/new-adventure.sh +++ b/scripts/new-adventure.sh @@ -55,15 +55,7 @@ The entire **infrastructure is pre-provisioned in your Codespace** ## ๐Ÿš€ Ready to Start? -[Choose your level](https://dynatrace-oss.github.io/open-ecosystem-challenges/00-$selected_slug/) and begin -learning! -EOF - - cat > "$ADVENTURE_DIR/mkdocs.yaml" << EOF -site_name: '$adventure_emoji 00: $adventure_name' - -nav: - - Introduction: index.md +[Choose your level](https://offon.dev/adventures/$selected_slug/) and begin learning! EOF cat > "$ADVENTURE_DIR/docs/index.md" << EOF @@ -209,8 +201,6 @@ The script will tell you which checks failed. Fix the issues and run it again. to claim your victory! ๐Ÿ† EOF - echo " - '$level_emoji $level_difficulty': $level_slug.md" >> "$ADVENTURE_DIR/mkdocs.yaml" - cat >> "$ADVENTURE_DIR/docs/index.md" << EOF ### $level_emoji $level_difficulty: $level_name @@ -220,10 +210,10 @@ EOF $level_summary -[**Start the $level_difficulty Challenge**](./$level_slug.md){ .md-button .md-button--primary } +[**Start the $level_difficulty Challenge**](./$level_slug.md) EOF - echo "โœ… Level doc created, added to mkdocs.yaml, and level card added to index.md." + echo "โœ… Level doc created and level card added to index.md." else echo "โ„น๏ธ Level doc already exists, skipping." fi @@ -245,7 +235,7 @@ SCRIPT_DIR="\$(cd "\$(dirname "\${BASH_SOURCE[0]}")" && pwd)" # shellcheck disable=SC1091 source "\$SCRIPT_DIR/../../../../lib/scripts/loader.sh" -DOCS_URL="https://dynatrace-oss.github.io/open-ecosystem-challenges/00-$selected_slug/$level_slug" +DOCS_URL="https://offon.dev/adventures/$selected_slug/levels/$level_slug" print_header \\ 'Challenge 00: $adventure_name' \\ @@ -397,5 +387,5 @@ gum style \ " .devcontainer/$DEVCONTAINER_NAME/" \ "" \ "$(gum style --foreground 245 "Need help? Check the contributing guide:")" \ - "$(gum style --foreground 245 "https://dynatrace-oss.github.io/open-ecosystem-challenges/contributing/adventures/")" + "$(gum style --foreground 245 "https://github.com/dynatrace-oss/open-ecosystem-challenges/blob/main/CONTRIBUTING.md#build-a-new-adventure")"