# Contributing

YASL is a small desktop surface/input library for application-owned loops and
renderers. Read [the guide](docs/guide.md) and [API policy](docs/api-policy.md).
Keep public C APIs direct: opaque surface pointers, plain IDs/numeric arguments,
and one tagged event. Avoid new descriptor/geometry/string/handle helper structs,
application runners, graphics engines, or hidden presentation policy.

Portable lifetime, event ownership, validation, and rendering bridges live in
src/common. Native implementations live in src/platform/wayland, x11, and cocoa.
Private backend geometry/frame/loop types are implementation details, not installed
API. Linux desktop services live in src/platform/freedesktop; POSIX synchronization
and waiting live in src/platform/posix. Keep native handles typed in extension headers.

Document public units, ownership, errors, thread requirements, callback timing,
and unsupported behavior. Add useful behavior coverage and examples. Run:

```sh
meson compile -C build
meson test -C build --print-errorlogs
```

Changes to portable/native behavior need both Linux backends and installed shared/
static consumers checked. Use the isolated GPU suite described in [testing](docs/testing.md).
Cocoa changes require a native macOS build/test; disclose platforms not exercised.
Do not edit generated protocol files for unrelated changes. Check exact exports and
public C/C++ compilation. Contributions use the project's MIT license.