diff options
Diffstat (limited to 'docs/api-policy.md')
| -rw-r--r-- | docs/api-policy.md | 37 |
1 files changed, 37 insertions, 0 deletions
diff --git a/docs/api-policy.md b/docs/api-policy.md new file mode 100644 index 0000000..d5c7159 --- /dev/null +++ b/docs/api-policy.md @@ -0,0 +1,37 @@ +# Public API policy + +YASL 0.1 is pre-release. The installed headers are the public API; implementation +headers under `src/` are private even when their symbols appear in a static +archive. The shared library exports only declarations from installed headers. +Native backend headers and accessors are available only for built backends. + +There is currently no stable ABI promise and no versioned shared-library SONAME. +Rebuild consumers against the exact headers/library pair they ship. Source and +binary compatibility can change before 1.0. Do not assume struct layout is stable +across releases, mix headers and binaries from different revisions, or persist +public structs as a file/network format. The package version is available through +`pkg-config --modversion yasl`. + +See [migration notes](migrating.md) for the portable keyboard and fractional +scroll API changes. + +API changes should keep ordinary CPU drawing usable with only `<yasl/yasl.h>` +and the C standard library. Prefer an explicit capability and an ordinary +unsupported result over backend names in portable application logic. Native +rendering and handles belong in the extension headers. Avoid adding engine, +widget, renderer, or application policy to the surface layer. + +Every public addition or behavior change needs: + +- A header contract describing arguments, result, units, lifetime, threading, + callback timing, and unsupported behavior where applicable. +- An update to the guide and its backend limits when observable behavior changes. +- A runnable example when the new workflow cannot be understood from an isolated + call, and meaningful regression coverage for ownership or behavior changes. +- A check that shared exports and installed-package consumers still work. + +Functions documenting errno set it on failure. Other booleans report acceptance +or availability without a guaranteed errno; void setters are best effort. +Callbacks and successful returns do not imply confirmed screen presentation. +See `yasl_timing.source` for provenance. Future changes that strengthen error +reporting must preserve these distinctions in documentation. |