From 3c1ee965ca9d38da3eed82a1b2e82d7eee0b98de Mon Sep 17 00:00:00 2001
From: John Kerl <kerl.john.r@gmail.com>
Date: Wed, 22 Dec 2021 18:37:24 -0500
Subject: [PATCH] Document exit codes

---
 docs/src/reference-main-overview.md    | 10 ++++++++++
 docs/src/reference-main-overview.md.in | 10 ++++++++++
 todo.txt                               | 17 ++++++-----------
 3 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/docs/src/reference-main-overview.md b/docs/src/reference-main-overview.md
index 7cec38192..cc9c3a0b3 100644
--- a/docs/src/reference-main-overview.md
+++ b/docs/src/reference-main-overview.md
@@ -103,3 +103,13 @@ a=wye,x_sum=0.777891
 * They take more keystrokes
 * There's more to learn
 * They're highly customizable
+
+## Exit codes
+
+When you do `echo $?` immediately after running a Miller command (or any shell command), that's the _exit code_.
+
+Miller's are as follows:
+
+* 0 for normal exit.
+* 1 if an error was encountered. There should be helpful text written to `stderr`; please [file a bug report](https://github.com/johnkerl/miller/issues/new), ideally with a reproducible scenario, if the text is either missing or unhelpful.
+* 2 if there was a `panic` in the Go runtime -- you'll see lots of stack-trace lines. Please [file a bug report](https://github.com/johnkerl/miller/issues/new), ideally with a reproducible scenario, if you ever see this.
diff --git a/docs/src/reference-main-overview.md.in b/docs/src/reference-main-overview.md.in
index 3f1db0ee6..413b358e7 100644
--- a/docs/src/reference-main-overview.md.in
+++ b/docs/src/reference-main-overview.md.in
@@ -62,3 +62,13 @@ GENMD-EOF
 * They take more keystrokes
 * There's more to learn
 * They're highly customizable
+
+## Exit codes
+
+When you do `echo $?` immediately after running a Miller command (or any shell command), that's the _exit code_.
+
+Miller's are as follows:
+
+* 0 for normal exit.
+* 1 if an error was encountered. There should be helpful text written to `stderr`; please [file a bug report](https://github.com/johnkerl/miller/issues/new), ideally with a reproducible scenario, if the text is either missing or unhelpful.
+* 2 if there was a `panic` in the Go runtime -- you'll see lots of stack-trace lines. Please [file a bug report](https://github.com/johnkerl/miller/issues/new), ideally with a reproducible scenario, if you ever see this.
diff --git a/todo.txt b/todo.txt
index a489e4758..2a3769572 100644
--- a/todo.txt
+++ b/todo.txt
@@ -10,10 +10,7 @@ PUNCHDOWN LIST
   - dup field names https://github.com/johnkerl/miller/issues/225
   - --ifs-regex & --ips-regex -- guessing is not safe as evidence by '.' and '|'
   - allow-repeat-ixs nidx perf mod w/o regex split string ...
-  - big-picture item @ Rmd (csv memes; and beyond); also webdoc intro page
 
-  - keep checking issues
-  - verslink old relnotes
   - fractional-strptime
   - cmp-matrices
   - all-contribs: twi dm
@@ -21,10 +18,6 @@ PUNCHDOWN LIST
   - `mlr put` -> coverart
   - 0b1011 olh/webdoc
   - rtd links somewhere
-  - rd -> dbr
-  - integrate:
-    > https://www.libhunt.com/r/miller
-    > https://repology.org/project/miller/information
   ? array/map fields: marshal as JSON_SINGLE_LINE
 
 * shebang
@@ -90,10 +83,6 @@ PUNCHDOWN LIST
 
 * kw olh for func and funct both
 
-* pre-release:
-  o check issues
-  o TODO in *.go & *.mi
-
 * doc
   o new-in-miller-6: missings:
     - dump syntax -- ?
@@ -125,6 +114,12 @@ PUNCHDOWN LIST
 ================================================================
 NON-BLOCKERS
 
+* integrate:
+  o https://www.libhunt.com/r/miller
+  o https://repology.org/project/miller/information
+
+* verslink old relnotes
+
 * more perf?
   - batchify source-quench -- experiment 1st
   - further channelize (CSV-first focus) mlrval infer vs record-put ?