docs(Contributing): Add note re. Autogenerated Schema Bindings
@@ -13,3 +13,31 @@ See [Writing Schema Definitions](docs/writing-schema-definitions.md)
### Writing `<type>.md` documentation
See [Writing Schema Docs](docs/writing-schema-docs.md)
+
+## Autogenerated Schema Bindings
+
+We derive language binding files such as [types.ts](./ts/types.ts),
+[types.py](./py/stencila/schema/types.py), and [types.R](./r/R/types.R) from
+the [schema YAML files](./schema/).
+
+Despite those files being auto-generated, there are a couple of reasons why it is useful to include them in this repository.
+
+- Having them so that packages can be installed from the Git repo e.g.
+
+```r
+devtools::install_github("stencila/schema", subdir = "r", upgrade = "ask")
+```
+
+```bash
+pip install -e git+https://github.com/stencila/schema.git#subdirectory=py
+```
+
+- Allows us to more easily compare changes to the bindings and potentially identify issues.
+
+However, since these files are derived from the YAML files, there is
+potential risk of the type bindings and schema YAML to drift out of sync.
+
+One remedy we have in place is to use [git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks).
+This allows us to automatically build the schema, detects changes in the bindings, and commit them prior to each push command.
+
+To see the exact steps being performed, please see the [`checkBindings`](./Makefile) command in the `Makefile`.
