67 lines
2.5 KiB
Markdown
67 lines
2.5 KiB
Markdown
# Research Compatibility Rules
|
|
|
|
PureYAML replaces behavior that is currently studied in the private
|
|
`PureYAMLResearch` repository. Compatibility work must be research-led and
|
|
implementation-independent.
|
|
|
|
## Mandatory Start Point
|
|
|
|
Before changing parser, scanner, composer, emitter, validation, or typed
|
|
Codable conversion behavior:
|
|
|
|
- inspect the matching source, tests, or fixtures in `PureYAMLResearch`;
|
|
- identify the observable behavior PureYAML should match or deliberately reject;
|
|
- write PureYAML tests that pin that behavior before or with the implementation;
|
|
- keep all public-package code original and dependency-free.
|
|
|
|
## Copying Boundary
|
|
|
|
Do not copy source from Yams, CYaml, libyaml, or research-only references into
|
|
`Sources/`. Use the research repository for behavior discovery only.
|
|
|
|
Allowed:
|
|
|
|
- exact behavioral assertions in PureYAML tests;
|
|
- attribution in `ATTRIBUTION.md` and design docs;
|
|
- small independently written fixtures that describe input and expected output.
|
|
|
|
Forbidden:
|
|
|
|
- copied parser, scanner, emitter, or encoder implementation code;
|
|
- C files, generated parser files, or external SwiftPM dependencies;
|
|
- compatibility claims that were not checked against the research source or a
|
|
deliberate PureYAML design decision.
|
|
|
|
## Test Contract
|
|
|
|
Every compatibility test must pin at least one of:
|
|
|
|
- exact parsed value tree;
|
|
- exact emitted YAML;
|
|
- exact decoded Swift value;
|
|
- exact encoded value tree;
|
|
- exact validation issue;
|
|
- exact path-aware decoding or encoding error;
|
|
- exact required absence check for fields that must not appear.
|
|
|
|
## Parser Compatibility Lessons
|
|
|
|
YAML compatibility is parser-state compatibility, not only value-model
|
|
compatibility. Indicator characters such as `-`, `?`, and `:` are meaningful
|
|
only after indentation, flow depth, and the current parser production are taken
|
|
into account.
|
|
|
|
When fixing scanner or parser behavior:
|
|
|
|
- preserve tests for the exact production corpus shape that failed, not only a
|
|
smaller feature in isolation;
|
|
- combine interacting YAML features in one regression fixture when the bug
|
|
requires their interaction;
|
|
- keep implementation fixes grammar-level and content-independent; never branch
|
|
on corpus file names, OpenAPI field names, vendor names, schema prefixes, or
|
|
other production-data fingerprints;
|
|
- for plain scalar continuation bugs, cover both sides explicitly:
|
|
- a more-indented continuation line that starts with an indicator but remains
|
|
text;
|
|
- a same-context indicator line that must remain a collection item.
|