docs: add CONTRIBUTING.md guidelines

2026-04-07 15:33:00 -04:00
parent 0941acf7fe
commit 3673e5692a
1 changed files with 50 additions and 0 deletions
@@ -0,0 +1,50 @@
+# How to contribute to Reface
+
+Thanks for showing interest in contributing to rbx-reface. This is mostly a solo developer project so any support is welcome!
+
+## Setup
+
+Tools are managed via [Rokit](https://github.com/rojo-rbx/rokit). Install Rokit first, then run:
+
+```
+rokit install
+```
+
+This installs [Rojo](https://rojo.space) and [Wally](https://wally.run) at the versions pinned in `rokit.toml`.
+
+To build the package:
+
+```
+rojo build --output build/build.rbxm
+```
+
+## Working on the module
+
+The code should be well typed, documented when needed (but as self-documenting as possible), and easy to modify. Don't be scared to break up small things into their own functions, tables, or even submodules (especially data).
+
+A few conventions to follow:
+
+- **Naming**: `camelCase` for functions and variables, `PascalCase` for type names.
+- **Types**: all function parameters and return values should be typed. Shared types live in `typing.luau`.
+- **String interpolation**: use backtick interpolation (`` `like {this}` ``) rather than `..` concatenation.
+- **Errors**: use `warn()` with a `rbx-reface: ` prefix for non-fatal issues, rather than `error()` or `print()`.
+- 
+## Working on the face databases
+
+The face databases (`faceByBundle.luau` and `faceByMesh.luau`) are generated - don't edit them by hand.
+
+`scripts/faces.csv` is a plain list of face asset IDs. When a new face is added or the list changes, regenerate the databases by running:
+
+```
+uv run scripts/codegen.py
+```
+
+The script hits the Roblox catalog API to resolve each face ID to its bundle, then resolves the bundle to its head mesh asset. It writes the results directly into `src/faceByBundle.luau` and `src/faceByMesh.luau`. It includes retry logic for rate limits, but may still be slow if you're adding many faces at once.
+
+Python 3.13+ is required. [uv](https://astral.sh/uv) handles the dependency (`requests`) automatically.
+
+## Opening issues and pull requests
+
+- For bugs, please include the relevant head or face asset ID.
+- For larger changes (new features, restructuring), open an issue first so we can verify where we're at before you put in the work.
+- For small fixes or database additions, a PR directly is fine.