better public interface and doxygen

1 files changed, 39 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..88674ca
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,39 @@
+# 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.