Contributing to the Frontier Fabric AgentOps RVAS

Thanks for your interest in improving this RVAS! This repo is an open teaching asset — the more real-world the challenges, hints, and coach guides are, the better the experience for the next customer team that runs it. Contributions of all sizes are welcome, from fixing a typo to authoring a brand-new challenge.

Ways to contribute#

Golden rule: challenges and coach guides travel together#

Every attendee-facing challenge in challenges/ has a matching instructor guide in coach/. If you change one, update the other in the same pull request so they never drift:

• A new task in a challenge needs a matching checkpoint + reference path in the guide.
• A renamed file needs its prev/next nav links and the coach cross-link updated.

House style#

Attendee challenges (challenges/) describe what to accomplish, not how:

1. A short "mission log" blockquote story hook at the top.
2. ## Objectives and ## Prerequisites.
3. ## Your mission — numbered task groups describing the goal, not click-by-click steps.
4. ## Success criteria — a verifiable checklist.
5. ## Hints — progressive disclosure inside <details><summary>…</summary></details> blocks.
6. ## Resources — links into resources/ and docs/.
7. A footer with ⬅️ Previous / ➡️ Next navigation links.

Coach guides (coach/) give instructors the answers:

1. A snapshot table (duration, difficulty, dependencies, business question).
2. Coaching objectives and a concrete reference path (exact commands/paths).
3. Checkpoint verification, a common-pitfalls table, talking points, and an "if they finish early" note.

Keep the three business questions — reliability, cost, performance — threaded through new content.

Making changes#

1. Fork the repo and create a topic branch: git checkout -b improve-challenge-04.
2. Make your changes. Keep relative Markdown links valid (challenge nav, coach cross-links, resources/ and docs/ references).
3. Open a pull request with a clear description of the change and which challenge(s)/guide(s) it affects.
4. For substantive changes, please open an Issue first so we can align on direction.

The website (GitHub Pages)#

The repo doubles as its own website at https://microsoft.github.io/frontier-fabric-agentops-rvas/. So visitors never have to leave the site, every Markdown file is pre-rendered into a branded HTML page that sits next to its source (challenges/challenge-01-agent-telemetry.md → challenges/challenge-01-agent-telemetry.html), and reference-implementation code is viewable in-place through code.html. The landing page (index.html) and the delivery composer (builder.html) tie it all together.

GitHub Pages serves this repo in legacy mode (the branch root, as-is) — there is no CI build — so the generated HTML is committed to the repo. If you edit any Markdown, regenerate the site so the pages match:

Copynpm install       # once, to get the `marked` renderer
npm run build      # regenerates all *.html pages + builder-data.json

What the build does:

• Renders every .md (outside .git, .agents, node_modules, tools) to a branded .html page.
• Rewrites links so navigation stays on the site: *.md → *.html, directories → their README.html (or the parent component page), and code files → the in-site code.html viewer.
• Regenerates builder-data.json (challenge metadata + dependencies) that powers builder.html.

Commit the regenerated *.html and builder-data.json alongside your Markdown change in the same PR. Do not hand-edit generated .html files or builder-data.json — your changes will be overwritten on the next build. Styling lives in assets/css/site.css; the generator lives in tools/build.js.

Reporting issues#

Use GitHub Issues for bug reports, unclear instructions, broken links, or environment/setup problems encountered during a run. Please include the challenge number, your environment (Azure region, Fabric capacity SKU), and what you expected vs. what happened.

Contributor License Agreement#

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

Code of Conduct#

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks#

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos is subject to those third-party's policies.