[WTH Core] Updated WTH documentation to include new GitHub Codespaces support#1203
Open
jrzyshr wants to merge 56 commits into
Open
[WTH Core] Updated WTH documentation to include new GitHub Codespaces support#1203jrzyshr wants to merge 56 commits into
jrzyshr wants to merge 56 commits into
Conversation
…archived "002-IntroToAI" hack
added link to 069 to the homepage
[Hack Update] 069-RealTimeAnalytics - add listing to WTH homepage
Testing md_in_html extension for pyseplling
- Author's Guide: Add GitHub Codespaces & DevContainers section with two-copy devcontainer pattern, customization guidance, and Codespace- relative file path references. Replace stale manual setup section with folder structure reference that links to Contribution Guide. Add getting-started cross-link to CONTRIBUTING.md at top. - Host Guide: Rewrite Student Resources section with three delivery options (Codespaces recommended, Local DevContainers, Manual Teams upload). Remove obsolete DownGit section. Add presentations upload reminder. - PR Review Process: Add DevContainer review checklist items (two copies in sync, workspace settings correctly commented/uncommented). - CONTRIBUTING.md: Add Documentation Map table for role-based navigation. Update Create New Hack Action description to mention devcontainer.json files. Update folder structure listing with .devcontainer entries. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Move Hack Folder Structure up as first sub-section with tree diagram - Update intro to explain the Action scaffolds all elements upfront - Remove all 'copy this template to X' language; replace with 'the Action placed this at X, customize it' - Keep links to each template as reference - Each element section now assumes templates are already in place and author just needs to replace content Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Hack Folder Structure: Add Lectures.pptx and Coach/README.md to tree diagram. Add note that Codespaces/DevContainer support is optional when running the Action. - Hack Description: Update Challenges subsection to describe it as the table of contents with pre-created links. Remove Repository Contents (now in Coach Guide). Shorten Prerequisites to reference Challenge 0. - Challenge Design: Update Challenge 0 bullet to reflect it's already scaffolded and covers environment setup (Codespaces/local) and cloud resources. Update nav links note to explain they're pre-created and how to add new challenges manually. - Student Resources: Add note about author responsibility for Challenge 0 prereqs if not using Codespaces. Rewrite file referencing section to cover both Codespaces paths and Resources.zip paths. Add note about coach responsibility for Resources.zip distribution. - Presentation Lectures: Reference the template Lectures.pptx deck placed by the Action. Mark as optional but highly recommended. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add clear intro listing two options: Codespaces (recommended) vs Resources.zip distribution - Describe the student Codespace experience: VS Code in browser with files, CLI tools, and extensions pre-installed - Move opt-out responsibility note (Challenge 0 prereqs) to the two-option intro for better visibility Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Split into two subsections: Coach Guide Home Page and Challenge Coach Guides - Coach Guide Home Page: describe README.md in /Coach, list major sections from the template (Introduction, TOC, Coach Prerequisites, Azure Requirements, Suggested Agenda, Repository Contents) - Challenge Coach Guides: describe Solution-XX.md files, link to template, keep existing guidance on what each should contain - Mark Coach's Guide as required (no longer optional) - Update TOC with new subsections Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace all variations ('Coach's Guide', 'Coaches Guide') with 'Coach Guide'
to match the compound noun pattern used by 'Student Guide' throughout the repo.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Remove redundant Documentation Map table (covered by How Can I Contribute) - Add sentence to intro distinguishing Contribution Guide from Author's Guide - Add 'Help Review Hack Content' as a new contribution option with link to PR Review Process guide Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the What The Hack documentation set to better separate “content design” guidance from “contribution process” guidance, and to introduce/standardize guidance around GitHub Codespaces / DevContainers in authoring, hosting, and PR review workflows.
Changes:
- Adds cross-links between the Contribution Guide and the Author’s Guide, and introduces a new “Help Review Hack Content” section.
- Expands the Author’s Guide and Host Guide with more explicit scaffolded structure guidance and Codespaces/DevContainer-oriented resource distribution guidance.
- Updates the PR review process checklist and spell-check wordlist to account for DevContainer-related terminology.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| CONTRIBUTING.md | Adds links to the Author’s Guide, adds reviewer guidance, and adds Codespaces/DevContainer instructions to the contribution workflow. |
| 000-HowToHack/WTH-PRReviewProcess.md | Adds a DevContainer verification checklist for reviewers. |
| 000-HowToHack/WTH-HowToHostAHack.md | Reworks “Student Resources” guidance into multiple distribution options including Codespaces and local DevContainers. |
| 000-HowToHack/WTH-HowToAuthorAHack.md | Rewrites/expands authoring guidance, including scaffolded templates/folder structure and Codespaces/DevContainers explanation. |
| .github/workflows/spell-check/.wordlist.txt | Adds new terms used by the updated documentation to the spell-check allowlist. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+56
to
+58
| **NOTE:** GitHub Codespaces/DevContainer support is optional when running the "Create New Hack" Action. If you choose not to enable Codespaces support, the `.devcontainer` folder and its `devcontainer.json` file will not be created. You can always add Codespaces support later by manually creating these files from the [DevContainer Template](devcontainerTEMPLATE.json). | ||
|
|
||
| If you do enable Codespaces support, there is also a root-level devcontainer entry created at `/.devcontainer/xxx-HackName/devcontainer.json` which is used for launching Codespaces from the WTH repo during development. See the [Student Resources](#student-resources) section for details. |
Collaborator
Author
There was a problem hiding this comment.
There is a separate PR queued that implements this. The updates are referring to that functionality.
| 1. As mentioned above, publish your resources in the WTH repo under the `..Student/Resources` folder of your hack | ||
| 2. Create a DownGit link to the "Resources" folder (or whatever sub-folder you want your attendees to download) | ||
| 3. Use the DownGit link you created in your Challenge text to provide the link to the attendees. | ||
| The **"Create New Hack" GitHub Action** automatically creates both copies from the [DevContainer Template](devcontainerTEMPLATE.json) when you scaffold a new hack. The Action takes care of uncommenting the workspace settings in the root-level copy and leaving them commented out in the hack-level copy. |
Collaborator
Author
There was a problem hiding this comment.
THis is handled in a separate PR
Comment on lines
+133
to
+137
| - Create two copies of the `devcontainer.json` file for GitHub Codespaces and local DevContainer support: | ||
| - `/.devcontainer/xxx-MyAwesomeHack/devcontainer.json` — for launching a Codespace from your fork during development | ||
| - `xxx-MyAwesomeHack/Student/Resources/.devcontainer/devcontainer.json` — for local DevContainer use by students | ||
|
|
||
| See the [Author's Guide](./000-HowToHack/WTH-HowToAuthorAHack.md#student-resources) for details on customizing and working with these files. |
| - `/.devcontainer` | ||
| - The `devcontainer.json` file for local DevContainer use. | ||
|
|
||
| You will also find a root-level devcontainer entry at `/.devcontainer/xxx-MyAwesomeHack/devcontainer.json` for launching Codespaces from your fork during development. |
Comment on lines
+35
to
+39
| - Verify DevContainer configuration: | ||
| - A `devcontainer.json` file exists in both `/.devcontainer/xxx-HackName/` and `../Student/Resources/.devcontainer/` | ||
| - Both copies are in sync (same features, extensions, and settings) | ||
| - The root-level copy (`/.devcontainer/xxx-HackName/devcontainer.json`) has `workspaceFolder` and `workspaceMount` settings uncommented and pointing to the correct hack folder | ||
| - The hack-level copy (`../Student/Resources/.devcontainer/devcontainer.json`) has `workspaceFolder` and `workspaceMount` lines commented out |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Comment on lines
+35
to
+39
| - Verify DevContainer configuration: | ||
| - A `devcontainer.json` file exists in both `/.devcontainer/xxx-HackName/` and `../Student/Resources/.devcontainer/` | ||
| - Both copies are in sync (same features, extensions, and settings) | ||
| - The root-level copy (`/.devcontainer/xxx-HackName/devcontainer.json`) has `workspaceFolder` and `workspaceMount` settings uncommented and pointing to the correct hack folder | ||
| - The hack-level copy (`../Student/Resources/.devcontainer/devcontainer.json`) has `workspaceFolder` and `workspaceMount` lines commented out |
Comment on lines
+145
to
+147
| The Action has placed challenge templates in your hack's `../Student` folder as `Challenge-00.md`, `Challenge-01.md`, etc. Open each one and replace the sample text with your challenge content. | ||
|
|
||
| **NOTE:** The Action has already created navigation links in each challenge file that link to the preceding challenge, the hack home page, and the next challenge. If you need to add additional challenges beyond what was scaffolded, copy the [Challenge Template](WTH-Challenge-Template.md) into your `../Student` folder and update the navigation links to follow the same pattern. Always use relative links (e.g., `"Challenge-XX.md"`) instead of absolute links (e.g., `"http://github.com/Microsoft/WhatTheHack/000-YourAwesomeHack/Student/Challenge-XX.md"`). |
| It is common to provide attendees with resources in order to complete the hack's challenges. One example is to provide the code for an application that the hack's challenges are based on. Another example might be to provide sample code files, artifacts, or templates that provide guidance for completing the hack's challenges. | ||
| It is common to provide attendees with resources in order to complete the hack's challenges. One example is to provide the code for an application that the hack's challenges are based on. Another example might be to provide sample code files, artifacts, or templates that provide guidance for completing the hack's challenges. | ||
|
|
||
| If your hack provides attendees with code or resources, they should be included with your hack's contents in the `../Student/Resources` folder. |
| You can view the DownGit project on GitHub here: <https://github.com/MinhasKamal/DownGit> | ||
| 1. **`/.devcontainer/xxx-HackName/devcontainer.json`** (root-level copy) | ||
| - This is the copy you will work with and test during development. | ||
| - It contains `workspaceFolder` and `workspaceMount` settings that point to your hack's `/Student/Resources` folder within the repo. |
| - This allows you to quickly launch a Codespace from your fork of the WTH repo to test your hack's environment as you are authoring it. | ||
|
|
||
| And you can use DownGit from its website here: <https://minhaskamal.github.io/DownGit/#/home> | ||
| 2. **`../Student/Resources/.devcontainer/devcontainer.json`** (hack-level copy) |
Comment on lines
+205
to
+207
| **If using Codespaces:** Refer to files relative to the Codespace root. Since the Codespace opens to the `/Student/Resources` folder, reference files relative to that location. | ||
|
|
||
| > *Example:* Given a file at `../Student/Resources/infra/deploy.sh` in the repo, your challenge text should say: *"Run the `deploy.sh` script in the `/infra` folder of your Codespace."* |
|
|
||
| If the hack you are hosting supports Codespaces, the student guide's Challenge 0 will include instructions for students on how to launch their Codespace. As a coach, you do not need to distribute any resource files to the students. | ||
|
|
||
| **NOTE:** Not all hacks support GitHub Codespaces yet. Check the hack's `/Student/Resources/.devcontainer` folder for a `devcontainer.json` file to confirm Codespaces support. |
Comment on lines
+163
to
+165
| - `/.devcontainer` | ||
| - The `devcontainer.json` file for local DevContainer use. | ||
|
|
Whowong
reviewed
Jun 23, 2026
| **NOTE:** In each challenge's markdown file, you should create navigation links to/from the previous & next challenges. Please use relative links (eg. `"/ChallengeXX.md"`) instead of absolute links (eg. `"http://github.com/Microsoft/WhatTheHack/000-YourAwesomeHack/Student/ChallengeXX.md"`) | ||
| The Action has placed challenge templates in your hack's `../Student` folder as `Challenge-00.md`, `Challenge-01.md`, etc. Open each one and replace the sample text with your challenge content. | ||
|
|
||
| **NOTE:** The Action has already created navigation links in each challenge file that link to the preceding challenge, the hack home page, and the next challenge. If you need to add additional challenges beyond what was scaffolded, copy the [Challenge Template](WTH-Challenge-Template.md) into your `../Student` folder and update the navigation links to follow the same pattern. Always use relative links (e.g., `"Challenge-XX.md"`) instead of absolute links (e.g., `"http://github.com/Microsoft/WhatTheHack/000-YourAwesomeHack/Student/Challenge-XX.md"`). |
Contributor
There was a problem hiding this comment.
I think we should either replace with the WTHAgent or at least include as a second option.
| 1. As mentioned above, publish your resources in the WTH repo under the `..Student/Resources` folder of your hack | ||
| 2. Create a DownGit link to the "Resources" folder (or whatever sub-folder you want your attendees to download) | ||
| 3. Use the DownGit link you created in your Challenge text to provide the link to the attendees. | ||
| The **"Create New Hack" GitHub Action** automatically creates both copies from the [DevContainer Template](devcontainerTEMPLATE.json) when you scaffold a new hack. The Action takes care of uncommenting the workspace settings in the root-level copy and leaving them commented out in the hack-level copy. |
Contributor
There was a problem hiding this comment.
I believe this is only handled if the author requests correct? I didnt want users to assume one is always provided
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request updates the What The Hack Author's Guide to clarify the content design process, provide better guidance on using the "Create New Hack" GitHub Action, and improve instructions for organizing and customizing hack content. The guide now emphasizes the use of scaffolded templates, explains the folder structure, and streamlines the instructions for prerequisites and challenge design.
Major documentation improvements:
README.mdfrom a template, and provided direct instructions to customize it. [1] [2]Improved guidance on hack structure and content: