60 lines
2.5 KiB
Markdown
60 lines
2.5 KiB
Markdown
# Shared Example Policies
|
|
|
|
Use this file for policy that applies to many worked examples. Individual example specs should link
|
|
here instead of repeating these rules.
|
|
|
|
|
|
## Status
|
|
|
|
Informative policy for `spec/scene/examples/`. It does not override canonical scene, DRP2, or API
|
|
specs.
|
|
|
|
|
|
## API Caveat
|
|
|
|
Example specs may use provisional names to describe the intended shape of an implementation. Treat
|
|
those names as pressure tests unless the installed headers already define them.
|
|
|
|
|
|
## Data And Cache Policy
|
|
|
|
- Prefer inline or deterministic synthetic data for small fixtures.
|
|
- Use public downloads only when the real dataset is essential to the pressure test.
|
|
- Every downloaded dataset needs a source URL, license/citation note, expected files, size budget,
|
|
cache location, and deterministic fallback or explicit "no fallback" statement.
|
|
- Runtime examples should not require network access after the cache is populated.
|
|
- Expensive preprocessing belongs in a script or documented bundle build step, not in the runtime
|
|
example.
|
|
- Real-dataset examples belong in the `scientific` lane only when source, access URL, license or
|
|
terms, citation or attribution, preprocessing command, prepared-data path, displayed encodings,
|
|
and generated-media redistribution status are recorded.
|
|
- Real-dataset showcases that do not yet satisfy the `scientific` provenance bar should stay in
|
|
`showcases` or `lab` with an explicit provenance TODO.
|
|
- Scientific examples should include scientific context, prepared-data provenance, generated-media
|
|
traceability, and the intended contact route when author feedback is requested.
|
|
- Do not publish generated media from a dataset until redistribution and derived-media terms are
|
|
clear.
|
|
|
|
|
|
## FramePlan And DRP2 Notes
|
|
|
|
Worked examples should name the scene pressure they exercise, but they should not restate the
|
|
generic scene -> FramePlan -> DRP2 contract. Link to:
|
|
|
|
1. `../pipeline/FRAME_PLAN.md` for producer-side frame structure,
|
|
2. `../pipeline/RESOURCE_MODEL.md` for logical resources,
|
|
3. `../pipeline/INVALIDATION_AND_CACHING.md` for dirty update policy,
|
|
4. `../../drp2/` for protocol and runtime details.
|
|
|
|
|
|
## Agent Pickup
|
|
|
|
Do not copy a large "Agent Pickup" block into every example. A compact metadata block is enough:
|
|
|
|
```markdown
|
|
> **Example status:** informative pressure test
|
|
> **Target:** C example | Python example | fixture | API sketch | preprocessing script
|
|
> **Data:** inline | synthetic | bundled cache | public download
|
|
> **Validation:** smoke | screenshot/readback | fixture | manual checklist
|
|
```
|