From ea3ab9c002eb314241f3c7ee7af1727eca18b135 Mon Sep 17 00:00:00 2001
From: John Lapeyre <jlapeyre@users.noreply.github.com>
Date: Tue, 26 Mar 2024 14:13:46 -0400
Subject: [PATCH] Add more documentation on contributing (#199)

---
 CONTRIBUTING.md | 34 ++++++++++++++++++++++++++++++++++
 README.md       |  2 ++
 2 files changed, 36 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3ea0f74..063c345 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,5 +1,39 @@
 ## Pull Requests
 
+### Debugging / Developing
+
+Set the environment variable `QASM3_PATH` to the directory containing the QASM 3 example you are working on.
+Alternatively, in the examples below, you can use the fully qualified path to `example.qasm`.
+
+Use `semdemo` to see how the parser/analyzer handles your example in `example.qasm`.
+You will usually be concerned with two data structures, which we call the AST and the ASG.
+In order to test construction of the ASG, the AST must be constructed without errors.
+
+#### The AST
+
+Run
+```shell
+cargo run --color always --example semdemo -- parse example.qasm
+```
+If parsing was successful, you should see something like
+```
+Found 3 stmts
+Found 0 parse errors:
+[]
+```
+followed by a representation of the AST.
+
+### The ASG
+If running `semdemo` with the option `parse` as above prints no syntax errors, then
+you can proceed to the ASG. Run
+```shell
+cargo run --color always --example semdemo -- semantic example.qasm
+```
+If there were in fact syntax errors in producing the AST, then this command will
+pretty-print those errors, but will not attempt to construct the ASG.
+Otherwise the ASG will be constructed, and any *semantic* errors found will be
+printed.
+
 ### Continuous Integration (CI)
 
 All pull requests must pass a CI check before being merged. You can check if CI will pass locally with
diff --git a/README.md b/README.md
index 825b962..f5efed7 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,8 @@ Issues with the tag include a bit more context than some other issues in order t
 planning on working on these issues in the immediate future.
 However, this does not mean you can't tackle an issue without this tag if is a better fit.
 
+There are a few more tips in [CONTRIBUTING.md](./CONTRIBUTING.md), as well as some later in this README.
+
 ### Crates (roughly one installable library per crate)
 
 The first three crates are based on tools for `rust` and `rust-analyzer`.