CONTRIBUTING.md

Contributing

Most contributions require a Contributor License Agreement (CLA). It confirms that you can and do grant us permission to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, the CLA bot checks whether you need an agreement and adds a label or comment to the PR. Follow the bot's instructions. You only need to do this once across all repositories using our CLA.

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 questions or comments.

Content architecture contract

Activity content lives under modules/<moduleId>/challenges/<slug>/. The build reads meta.yml as the single source of truth and copies README.md into the generated Pages data. Do not hand-edit generated files under docs/assets/data/; run npm run build instead.

Outcome journeys live in outcomes.json. Group existing activities there without duplicating their content.

Every activity directory must contain:

meta.yml   # catalog metadata and dependency contract
README.md  # customer delivery team guide, hints, expected outputs, common failures

Start every activity guide with a short Session outcome: paragraph before the first section. Say what participants will have and how they can check it. Describe the guide's existing work without adding deliverables. Make clear when a fallback replaces a live result. Forwarding pages need only a direct link to their target guide.

Session value

Each active session must leave a useful GitHub adoption result. Configure a feature the team needs, migrate a working repository, or complete a reviewed change under the intended controls. A reusable operating check also qualifies when a named owner runs it on real data.

Explain why the setting or command matters beside the step that uses it. Supply the UI path, command, or starter needed to act, then show how to verify the result. Put deeper teaching in optional references.

Reuse working controls. Do not require extra tools, sample tasks, or comparison exercises just to cover a topic. Keep evidence in the existing PR or work item. Prefer native GitHub features. A reporting or storage helper belongs beside the task that needs it; building the helper alone does not justify a session. Use an assessment or fixture to prepare for setup, not to claim a live result. Without the required approval or feature, record the blocker.

meta.yml required fields

Field	Contract
id	Globally unique activity ID. Use <module>-<local-id> (ghec-ch01, ghas-02, ghaw-21). IDs are stable and may have intentional gaps.
title	Short catalog title.
module	One of ghec, ghas, ghaw.
track	Track slug for the module; must match docs/build.js module config.
difficulty	beginner, intermediate, or advanced.
duration_minutes	Estimated time for a delivery team member in minutes.
prerequisites	Activity ids to complete first. An empty list means the activity only needs its stated environment setup.
prerequisite_capabilities	Skills or access needed before starting; do not use this for activity ids.
description	One plain-text sentence, at most 100 characters and 16 words. State the main goal; keep steps and qualifications in the delivery guide. The build enforces these limits.
tags	Search/filter terms. Use lowercase kebab-case where possible.
app_dependency	Runtime/sample dependency (none, juice-shop, contoso-claims, contoso-app, seed, or seed-repo).
emu_compatible	true when the activity works in an EMU-controlled org; otherwise false.
min_environment	Lowest required scope: org, repo, codespace, or enterprise for activities that require enterprise-owner or enterprise-policy access beyond a single organization.
provision_creates	Names of resources that setup or delivery team members create. An empty list is allowed.
source_repo	Source repository provenance.
source_path	Repository-relative source path. Do not use absolute paths or ...
license	Source license; currently MIT.

Optional fields:

Field	Contract
display_order	Optional numeric position within an activity's catalog track. It defaults to the trailing number in the activity id and must stay unique within an active module catalog. Outcome filters use the challenge_ids order from outcomes.json.
tier	setup, core, stretch, or bonus. Defaults to core in the build.
references	Source-backed docs and product links used by customer delivery team members.
outcomes	Optional outcome tags. Add the activity to the outcome's challenge_ids in outcomes.json so users can find it under that result.
personas	Personas such as platform-engineer, security-lead, developer, or migration-lead.
business_value	Value tags such as reduce-migration-risk, shift-left-security, or automate-repetitive-work.
adoption_stage	assess, pilot, scale, or operate.

Outcome journey contract

outcomes.json uses schema_version: 1 and defines the outcomes shown on the homepage and catalog filters. Each outcome requires:

Field	Contract
id	Stable kebab-case outcome id.
name	Customer adoption journey name.
tagline	Short card summary.
description	Longer explanation of when to use the journey.
personas	Primary audience for the journey.
adoption_stage	Stages covered by the journey: assess, pilot, scale, operate.
business_value	Searchable value tags.
source_platforms	Relevant starting platforms, such as azure-devops, bitbucket, gitlab, github, or greenfield.
challenge_ids	Ordered list of active activity IDs for this outcome. IDs must be unique within the list. The catalog shows all of them without another selection.
success_metrics	Results the customer's team can verify in production in their GitHub organization or Azure tenant.

Include activities that help achieve the outcome. The list supports discovery; teams select the chapters they need and check each chapter's prerequisites. A diagnostic pilot does not prove that an agent can produce reviewed code changes. Follow the completion evidence rules.

Per-activity QA rubric

Use this 100-point rubric for every new or materially changed activity. Record manual review results in PR comments or issue bodies, not in throwaway repo planning files.

Area	Points	Pass standard
Metadata and provenance	15	Required fields complete; ids stable; module/track valid; source attribution present; generated catalog matches source.
Independence and setup	20	Activity can be started from a clean environment with only listed prerequisites/capabilities; no hidden state from previous activities; app dependency acquisition is documented.
Customer delivery team guide quality	35	README has a clear goal, practical steps, useful hints, expected outputs, timing guidance, common failure modes, cleanup notes where needed, and no dead or internal-only links, without leaking secrets.
Implementation evidence	15	Build/audit pass; stated outputs are observable; commands are current; external dependency versions or availability claims are source-backed.
Accessibility and operational safety	10	Works in intended org/account type; calls out Azure/billing/permissions risk; avoids destructive defaults and committed secrets.
Catalog fit and coverage	5	Activity fills a real module/track need, avoids unnecessary duplication, and has useful tags for discovery.

Score bands:

Score	Decision
90-100	Ship-ready.
75-89	Accept with tracked follow-ups; no P0/P1 issues.
60-74	Needs revision before merge unless explicitly approved as temporary scaffold.
0-59	Reject or rebuild.

Severity levels:

Severity	Definition	Merge policy
P0	Build/audit failure, broken prerequisite graph, missing guide, unsafe instruction, secret exposure, or activity cannot start.	Blocks merge.
P1	Core learning path fails, hidden dependency, stale product instruction, dead required link, or misleading required outcome.	Blocks merge unless owner accepts documented risk.
P2	Delivery guide quality gap, weak evidence, missing optional metadata, incomplete cleanup, or confusing catalog fit.	May merge with assigned follow-up.
P3	Editorial polish, tag improvement, minor timing mismatch, or optional reference update.	Non-blocking.

QA inventory format

Use one inventory object per activity. Write JSON Lines in PR comments, issue bodies, or local reports so tools can compare review results. Do not add planning files to the repository.

{"id":"ghas-02","reviewed_at":"2026-06-19T09:05:03+02:00","reviewer":"name-or-role","score":92,"severity":"P3","decision":"ship","evidence":["npm run build","npm run audit","cold-start runbook followed"],"findings":[{"severity":"P3","area":"tags","summary":"Add oauth tag if the guide gains OAuth steps."}],"missing_candidate_decision":"none"}

Allowed decision values: ship, ship-with-followups, revise, reject, defer, candidate-accepted, candidate-declined.

Required inventory keys: id, reviewed_at, reviewer, score, severity, decision, evidence, findings, missing_candidate_decision.

Catalog coverage and backlog decisions

Use these rules when deciding whether a missing activity belongs in the backlog:

1. Preserve current scoped modules before adding new scope.
2. Prefer a gap-filling activity over a duplicate topic.
3. Do not restore intentionally removed ids unless the original scope decision is reversed.
4. If a candidate needs a new product area, create a new module/track proposal rather than stretching an existing module.
5. Every accepted candidate needs an owner, source/provenance, dependency plan, and QA inventory entry before content work starts.