From 08c6fd1a754bace603a51f394293269778e8433e Mon Sep 17 00:00:00 2001
From: Raminder Singh <romi_ssk@yahoo.co.in>
Date: Fri, 27 Sep 2024 11:43:17 +0530
Subject: [PATCH 1/2] expand the testing and debugging sections of contributing
 guide

---
 docs/contributing.md | 38 +++++++++++++++++++++++++++++++-------
 1 file changed, 31 insertions(+), 7 deletions(-)

diff --git a/docs/contributing.md b/docs/contributing.md
index ec9c6205..aa65761c 100644
--- a/docs/contributing.md
+++ b/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 and install the latest `pg_graphql` in the Postgres instance specified by `pg_config`. This step is needed when you have made any changes in the Rust code.
+
+Next, run all the tests by executing:
+
+```bash
+./bin/installcheck
+```
+
+You can combine the last two steps to quickly 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.

From ea5ee39ce61e9d2697de182bbb02cffe0b196f02 Mon Sep 17 00:00:00 2001
From: Raminder Singh <romi_ssk@yahoo.co.in>
Date: Fri, 27 Sep 2024 11:50:56 +0530
Subject: [PATCH 2/2] refine the docs language

---
 docs/contributing.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/contributing.md b/docs/contributing.md
index aa65761c..9097ed18 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -17,7 +17,7 @@ To run tests locally, first execute:
 cargo pgrx install
 ```
 
-to build and install the latest `pg_graphql` in the Postgres instance specified by `pg_config`. This step is needed when you have made any changes in the Rust code.
+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:
 
@@ -25,7 +25,7 @@ Next, run all the tests by executing:
 ./bin/installcheck
 ```
 
-You can combine the last two steps to quickly run all the tests:
+You can combine the last two steps to build and install `pg_graphql` and run all the tests:
 
 ```bash
 $ cargo pgrx install; ./bin/installcheck