Change and Test Surface Guidance
Providers publish concise recipient guidance describing what changed and what surface area should be tested.
Structured Requirements
Patch providers should publish versioned recipient guidance describing what changed and what surface area should be tested.
| Check | Severity | Evidence |
|---|---|---|
|
EVD-001.CHECK-001 Recipient guidance uses the current guidance schema |
observe | recipient_guidance, schema_version |
Requirement
Patch providers SHOULD publish a recipient-facing summary alongside each patch that describes:
- what changed;
- why the change was made;
- whether the patch is an upstream backport or provider-developed fix;
- what application surface area recipients should consider testing;
- references to OpenRewrite recipes, markdown, LLM-friendly context, or other machine-readable guidance when available.
Rationale
Financial services consumers need more than a coordinate. They need enough context to evaluate the patch, route testing, and explain adoption decisions internally.
Suggested schema
recipient_guidance:
schema_version: 0.1.0
what_changed:
- Short, concrete change summary.
suggested_test_surface:
- APIs, frameworks, configuration paths, or runtime behaviors to test.
automation:
openrewrite_recipes:
- org.example.security.ExampleRecipe
llm_context: docs/patch-context.md
The draft schema is published at /schemas/osera-recipient-guidance-0.1.0.schema.json.
Maturity note
This is an intentionally early standard. The working group should refine the minimum fields and decide which parts belong in feeds, release notes, repository files, or separate evidence bundles.
This is deferred from OSERA-SP-0.1.0 because the working group has not yet defined the expected format tightly enough to make it advisory or required for the first ratification decision. It should run in observe mode and be reconsidered for OSERA-SP-0.2.0.
Illustrative evidence
See OSERA Commit Evidence for legacy proof-of-concept illustrations. These historical examples do not establish conformance with the ratified pack. Current release examples use the OSERA-SP-0.1.0 naming conventions.