docs: add sample creation quick guide

[Sheri Gilley (sdgilley)]

Adds a concise entry point for contributors who need to create a metadata-bearing sample and understand how it is validated.

The guide distinguishes build-readiness-only samples from samples that opt into live-service validation, provides the minimum sample.yaml shape and local validation commands, and links to the detailed validation contracts.

[Copilot]

🟡 Changes recommended

The quick guide contains unresolved inaccuracies about supported languages, validation scope, cadence, and substitutions.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a contributor quick guide for creating metadata-bearing samples and understanding validation modes.

Changes:

• Adds CREATE_SAMPLE.md with metadata examples and local validation commands.
• Links the guide from repository and contribution documentation.
• Documents validation environment variables, contracts, and cadence behavior.

File summaries

File	Description
README.md	Links to the quick guide.
CREATE_SAMPLE.md	Adds sample creation and validation guidance.
CONTRIBUTING.md	Directs contributors to the guide.
.github/validation-pilot.README.md	Documents cadence variables and references.
.github/scripts/validate-sample.README.md	Updates validation contract documentation.

Review details

Suppressed comments (5)

CREATE_SAMPLE.md:53

• The build-readiness step is not unconditional: Go is supported by PR/local validation but is excluded from cadence discovery, and Rust samples are explicitly skipped. Since this section describes the daily cadence as well, Always runs is inaccurate for those samples.

- **Build Readiness:** Always runs build/compilation checks on PR touches and daily cadence.

CREATE_SAMPLE.md:26

• The validator treats any declared build, validate, or test command as authoritative and does not fill omitted commands from the language default (run_sample_yaml returns success after the declared commands). This wording can lead a contributor who declares only build to assume the default compile step still runs.

# Optional: Custom build & compile overrides (language defaults used if omitted)

CREATE_SAMPLE.md:109

• The build-readiness invocation shown immediately below does not execute or honor live_service_validation; that block is used only by the separate --mode live-service invocation. As written, this suggests a normal --language run will run the live-service command whenever the block is present, contrary to the validator's separate-mode contract.

works whether or not the sample has a `sample.yaml` — without one, the script
falls back to the language's default build/compile check; with one, it honors any
declared `build`/`validate`/`test` commands or `live_service_validation` block.

CREATE_SAMPLE.md:64

• The validator writes substitutions into the target file in place and does not restore it after the command. Because this guide also provides a local live-service invocation, saying it patches the workflow checkout hides that local runs can leave the endpoint or deployment value in the contributor's working tree; warn users to run on a disposable copy or restore the files afterward.

runtime. Declare a `substitutions` list under `live_service_validation` to have the
validator patch the placeholder in the workflow checkout, using an environment
variable, before running the command:

CREATE_SAMPLE.md:115

• The local command uses <language> while the guide lists javascript, but validate-sample.sh rejects --language javascript; only workflow callers map JavaScript paths to the typescript validator. Add that mapping here so a JavaScript contributor does not copy the listed language into a command that exits with an unsupported-language error.

bash .github/scripts/validate-sample.sh \
  --language <language> \
  --sample-dir samples/<language>/<sample-name>

• Files reviewed: 5/5 changed files
• Comments generated: 4
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.