Skip to content

docs + devcontainer: fix scaffolding step, Azure AD rename, and Codespaces launch speedup#48

Open
keith-oak wants to merge 3 commits into
microsoft:mainfrom
keith-oak:workshop-improvements
Open

docs + devcontainer: fix scaffolding step, Azure AD rename, and Codespaces launch speedup#48
keith-oak wants to merge 3 commits into
microsoft:mainfrom
keith-oak:workshop-improvements

Conversation

@keith-oak

Copy link
Copy Markdown

Summary

Three independent, low-risk improvements that showed up while I was preparing to deliver this workshop. Each is in its own commit so they can be reviewed, split, or dropped individually.

Commit What Closes
7c9b2a5 Rename Azure AD → Microsoft Entra ID in English and Japanese workshop intros #47
7ec45fb Clarify the Create C# Scaffolding step so it points attendees at .github/copilot-instructions.md (and explains the .github/instructions/ folder is a different mechanism) #46
e407772 Speed up Codespaces launch for conference wifi — switch .NET install from wget + dotnet-install.sh to the devcontainer feature, drop unused apt packages, pre-warm NuGet via onCreateCommand, and add a prebuild trigger workflow

Details

1. Azure AD → Microsoft Entra ID (#47)

Microsoft rebranded Azure AD to Microsoft Entra ID. Four occurrences updated across docs/en/workshop-introduction.md and docs/ja/workshop-introduction.md. Pure docs change, no behaviour impact.

2. Clarify Copilot Instructions step (#46)

The Create C# Scaffolding step currently tells attendees to edit .github/instructions/instructions.md, describing it as an empty pre-created file. In practice:

  • .github/instructions/ already ships with three populated files (csharp-migration.instructions.md, python-analysis.instructions.md, testing.instructions.md) — these are glob-scoped via applyTo frontmatter and shouldn't be edited for this step.
  • The actual target is .github/copilot-instructions.md at the repo root. It ships pre-populated with Python-focused guidance that attendees need to replace, not append to.

The English and Japanese versions of create-csharp-scaffolding.md are updated to:

  1. Point at the correct path (.github/copilot-instructions.md)
  2. Say "replace the entire contents" rather than "fill in an empty file"
  3. Include an inline admonition explaining the distinction between .github/copilot-instructions.md (single repo-wide) and .github/instructions/ (glob-scoped applyTo files)

3. Codespaces launch speedup

Workshop attendees typically launch the Codespace for the first time on conference or venue wifi, where cold-start download cost is what determines whether they spend their first 10 minutes waiting or exercising. This commit reduces that cost without touching any workshop content:

  • .NET via devcontainer feature (ghcr.io/devcontainers/features/dotnet:2) instead of wget + dotnet-install.sh. Features are cached by Codespaces across rebuilds and are baked into prebuild images — the ~200 MB SDK download stops happening on every cold build.
  • Drop wget, curl, build-essential from the apt layer. They were there to bootstrap dotnet-install.sh; with the feature move they're unused, and the pinned Python deps (FastAPI, uvicorn, httpx, requests, pytest) install from wheels.
  • onCreateCommand: dotnet restore against src/csharp-app-complete so NuGet is warm before the attendee's first dotnet run.
  • .github/workflows/codespaces-prebuilds.yml as a trigger/marker workflow — fires on push to main and on devcontainer/requirements changes. The actual prebuild runs on GitHub's Codespaces infrastructure and must also be enabled in Settings → Codespaces → Set up prebuild. Once that's enabled, attendees should see cold-start drop from several minutes to well under a minute.

No changes to attendee-facing files, workshop flow, or reference implementations.

Out of scope (deliberately)

Test plan

  • Re-read the modified create-csharp-scaffolding.md in both languages end-to-end and confirm the wording still makes sense
  • Confirm four Azure AD occurrences in both workshop-introduction.md files are now Microsoft Entra ID
  • Launch a Codespace from this branch on a cold image, time the "ready to work" interval, compare to a cold launch from main
  • Verify dotnet --version returns 10.0.x inside the Codespace
  • mkdocs build against docs/mkdocs.yml to catch any markdown rendering issues from the new admonition
  • Enable Codespaces prebuilds in repo settings so the workflow has something to trigger

Thanks to the workshop team for the care that's gone into this repo — it's a genuinely useful piece of material. Happy to split this PR, rework the wording, or drop any commit on request. 🙌

Microsoft rebranded Azure AD to Microsoft Entra ID. The workshop
introduction referenced the legacy name in both English and Japanese
docs; update all occurrences so attendees see the current product name.

Fixes microsoft#47
The Create C# Scaffolding step instructed attendees to edit
'.github/instructions/instructions.md' — but that path is used for
glob-scoped instruction files (which already exist and are populated),
not for the repository-wide Copilot Instructions file.

The actual target is '.github/copilot-instructions.md' at the repo root,
which ships pre-populated with Python-focused guidance. Attendees need
to replace its contents, not fill in an empty file.

Changes in both English and Japanese versions:

- Point to the correct path: '.github/copilot-instructions.md'
- Clarify that the contents must be replaced, not appended
- Add an inline note explaining the difference between
  '.github/copilot-instructions.md' (single repo-wide file) and
  '.github/instructions/' (glob-scoped applyTo files)

Fixes microsoft#46
Workshop attendees frequently launch the Codespace for the first time on
conference or venue wifi, where cold-start download cost is the dominant
factor in how quickly they can start the hands-on exercises. This change
reduces that cost without altering any workshop content or flow.

Changes

- Install .NET via devcontainer feature (ghcr.io/devcontainers/features/dotnet:2)
  instead of 'wget + dotnet-install.sh' in the Dockerfile. Features are
  cached by Codespaces across rebuilds and are baked into prebuild images,
  so the ~200 MB .NET SDK download no longer happens on every cold build.

- Drop 'wget', 'curl', and 'build-essential' from the Dockerfile apt layer.
  They were only required to bootstrap dotnet-install.sh; the pinned Python
  dependencies (FastAPI, uvicorn, httpx, requests, pytest) build from wheels
  and do not need a C toolchain.

- Add 'onCreateCommand' that runs 'dotnet restore' against
  'src/csharp-app-complete' during container creation, so the NuGet cache
  is warm before attendees reach the first 'dotnet run'.

- Add '.github/workflows/codespaces-prebuilds.yml' as a trigger/marker
  workflow. It runs on push to main and whenever devcontainer config or
  Python requirements change — signalling when a prebuild refresh is
  appropriate. The actual prebuild runs on GitHub's Codespaces
  infrastructure and must also be enabled in
  Settings -> Codespaces -> Set up prebuild.

No changes to attendee-facing files, workshop docs, or the reference
implementations in 'src/csharp-app-complete' or 'src/python-app'.
@keith-oak

Copy link
Copy Markdown
Author

Tagging folks who look like the right reviewers based on recent merge history and issue authorship — apologies for the mention noise, feel free to re-route:

Suggested labels if a maintainer can apply them: documentation, enhancement.

I couldn't self-assign reviewers or labels (fork PR from an external contributor), so happy for anyone with maintainer perms to route this as they see fit. 🙏

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant