# Contributing

YASL focuses on desktop surfaces for applications that own their renderer.
Read the [API policy](docs/api-policy.md) and [application guide](docs/guide.md)
before changing public behavior. Keep backend details in native extensions and
make common operations usable through the portable headers.

Shared API behavior and backend interfaces live in `src/common/`. Native
windowing implementations, key mappings, and typed native accessors live in
`src/platform/<backend>/`; keep their generated protocols with the backend.
OS support shared by multiple backends lives separately in `src/platform/posix/`
and is selected by `src/platform/meson.build`. It currently supplies the event
loop and the private mutex implementation used through `platform/sync.h`.
Common code should depend on these internal interfaces rather than native OS
headers. Keep public headers in `include/yasl/` and tests in `tests/<backend>/`.

For a future Win32 backend, add `src/platform/win32/`, select its event loop and
`yasl_platform_sync.h` in the platform build, and register its backend through
the common dispatch interface. Windows still needs build/dependency selection,
public API/export support, and ports of POSIX-based examples and test harnesses;
the directory structure alone does not provide Windows support.

For a bug report, include the revision, operating system, selected backend from
`yasl_display_backend()`, capability mask, compiler, build options, reproduction
steps, and a small example if possible. For input issues include the relevant
event fields, layout/device/driver, and whether the issue occurs on another
backend. Report observations separately from expected behavior.

Build and test with:

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

See [testing](docs/testing.md) for isolated Linux integration tests, sanitizer
builds, and native tablet tests. Changes to shared behavior need both backend
configurations checked. Cocoa changes need a macOS desktop build/test; Linux
success alone does not validate them. Keep changes focused and describe any
platforms that were not exercised.

Document public behavior in the public header first: argument validity,
units, ownership/lifetime, return/error behavior, thread requirements, callback
rules, and unsupported results. Update guides/examples when the workflow
changes. Use zero-initialized specs and check fallible operations in examples.
Build the reference with `doxygen Doxyfile`; warnings are errors. Do not edit
vendored generated protocol files for unrelated changes.

Use the existing C style and `yasl_`/`YASL_` public names. Run the tests relevant
to the changed behavior, including shared exports and public C/C++ compilation.
For a pull request, explain the observable problem, resulting behavior, and
validation, including any native tests still needed. Contributions use the
project's MIT license.