Merge pull request #560 from supabase/contributing-docs

Expand contributing guide

docs/contributing.md

@@ -2,29 +2,53 @@ pg_graphql is OSS. PR and issues are welcome.
 
 ## Development
 
-Requirements:
+To start developing `pg_graphql`:
 
-- rust
-- cargo
-- [pgrx](https://github.com/tcdi/pgrx)
+1. [Install Rust](https://www.rust-lang.org/tools/install).
+2. [Install pgrx](https://github.com/pgcentralfoundation/pgrx)
 
 ### Testing
 
-Tests are located in `./test/sql` with expected output in `./test/expected`
+Tests are located in sql files in the `./test/sql` folder. Each sql file has a corresponding expected output file in `./test/expected` folder. For example, `./test/sql/aliases.sql`'s expected output is in `./tests/expected/aliases.out`. When a test runs, its actual output is saved in the `./results` folder. If the file in `./results` folder matches the corresponding file in the `./test/expected` folder, the test passes, otherwise it fails.
 
-To run tests locally, execute:
+To run tests locally, first execute:
+
+```bash
+cargo pgrx install
+```
+
+to build `pg_graphql` from source and install it in the Postgres instance specified by `pg_config`. This step must be run when you have made any changes in the Rust code. It can be skipped if there are no Rust code changes since the last time the command was run. The skipping is expecially useful when you are only modifying the test sql files.
+
+Next, run all the tests by executing:
+
+```bash
+./bin/installcheck
+```
+
+You can combine the last two steps to build and install `pg_graphql` and run all the tests:
 
 ```bash
 $ cargo pgrx install; ./bin/installcheck
 ```
 
+You can run a single test by passing its name to the `installcheck` command. For example, the following runs the test in `./test/sql/aliases.sql`.
+
+```bash
+./bin/installcheck aliases
+```
+
+When writing a new test, or editing an existing one, the file in `./result` should be inspected manually and then copied over to the `./test/expected` folder to make the test pass.
+
+### Debugging
+
+You can print to the output by using the `pgrx_pg_sys::submodules::elog::info!` macro in the Rust code. Lines printed with this macro will show in the .out file in the `./results` folder.
 
 ### Interactive PSQL Development
 
 To reduce the iteration cycle, you may want to launch a psql prompt with `pg_graphql` installed to experiment
 
 ```bash
-cargo pgrx run pg14
+cargo pgrx run pg16
 ```
 
 Try out the commands below to spin up a database with the extension installed & query a table using GraphQL. Experiment with aliasing field/table names and filtering on different columns.