diff options
Diffstat (limited to 'docs/api-policy.md')
| -rw-r--r-- | docs/api-policy.md | 48 |
1 files changed, 14 insertions, 34 deletions
diff --git a/docs/api-policy.md b/docs/api-policy.md index 3e510f3..f2f4d92 100644 --- a/docs/api-policy.md +++ b/docs/api-policy.md @@ -1,38 +1,18 @@ # Public API policy -YASL 0.1 is pre-release. The headers under `include/yasl/` 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 public headers. -Native backend accessors are exported only for built backends. Installation -copies both libraries, public headers, enabled native headers, and pkg-config metadata. +YASL is pre-release 0.1. Source and ABI compatibility are not guaranteed. Rebuild +consumers against matching installed headers/library; do not serialize public events +or assume their layout is a stable file/network format. -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 release version is declared in -`meson.build`. +Only installed include/yasl headers are public. The surface library exposes an +opaque surface and one tagged event record, with direct C arguments and ordinary +pointer/integer results. Native backend headers, geometry records, callbacks, loops, +and drawing targets under src are private even when a static archive contains them. +The shared library exports exactly the installed public declarations. -See [migration notes](migrating.md) for window creation, 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 consumers of the installed library 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. +Do not restore removed runner/frame/display APIs or compatibility aliases. Keep +rendering bridges separate from the portable surface/input core and preserve the +application's ownership of GPU resources and its loop. Public additions need clear +units, ownership, thread/callback timing, errors and unsupported behavior, useful +examples, and behavior coverage. Update the guide and test installed shared/static +consumers and exports. Changes affecting Cocoa need a native macOS build/test. |