# 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.

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 installed 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.