From 43d1e1035dc7d5d5cea5576b6b5cf0d9415438fa Mon Sep 17 00:00:00 2001
From: Michael Orlitzky <michael@orlitzky.com>
Date: Sat, 14 Jun 2014 21:06:59 -0400
Subject: [PATCH] New documentation: README.development.

---
 doc/README.development | 49 ++++++++++++++++++++++++++++++++++++++++++
 htsn-import.cabal      |  1 +
 2 files changed, 50 insertions(+)
 create mode 100644 doc/README.development

diff --git a/doc/README.development b/doc/README.development
new file mode 100644
index 0000000..b1df698
--- /dev/null
+++ b/doc/README.development
@@ -0,0 +1,49 @@
+== Pickle Failures ==
+
+Our schemas are "best guesses" based on what we've seen on the
+wire. From time to time they'll be wrong, and thus the (un)pickler
+implementation will fail to unpickle some XML document. The easiest
+way to test a fix for this is interactively: it's quick, and error
+messages are written to the console. Here's an example of such a
+session (wrapped for readability):
+
+  $ ghci
+  htsn-import> runX $ xunpickleDocument
+                      TSN.XML.AutoRacingResults.pickle_message
+                      parse_opts
+		      "schemagen/AutoRacingResultsXML/21241892.xml"
+  [Message {xml_xml_file_id = 21241892... stamp = 2014-06-08 04:05:00 UTC}]
+
+If there's an error, you'll see something like the following:
+
+  $ ghci
+  htsn-import> runX $ xunpickleDocument
+                      TSN.XML.AutoRacingResults.pickle_message
+                      parse_opts
+		      "schemagen/AutoRacingResultsXML/21241892-bad.xml"
+  fatal error: document unpickling failed
+  xpElem: got element name "RaceDate", but expected "RaceID"
+  context:    element "message"
+  contents:   <Title>IRL - Firestone 600 - Final Results</Title><Track_Location>
+  Texas Motor Sp...
+  []
+
+
+== Creating the Database Schema (Deployment) ==
+
+When deploying for the first time, the target database will most
+likely be empty. The schema will be migrated when a new document type
+is seen, but this has a downside: it can be months before every
+supported document type has been seen once. This can make it difficult
+to test the database permissions.
+
+Since all of the test XML documents have old timestamps, one easy
+workaround is the following: simply import all of the test XML
+documents, and then delete them. This will force the migration of the
+schema, after which you can set and test the database permissions.
+
+Something as simple as,
+
+  $ find ./test/xml -iname '*.xml' | xargs htsn-import -c foo.sqlite
+
+should do it.
diff --git a/htsn-import.cabal b/htsn-import.cabal
index 57b00c8..d381b15 100644
--- a/htsn-import.cabal
+++ b/htsn-import.cabal
@@ -12,6 +12,7 @@ extra-source-files:
   doc/htsn-importrc.example
   doc/man1/htsn-import.1
   doc/README.dbschema
+  doc/README.development
   doc/README.schemagen
   doc/TODO
   makefile
-- 
2.43.2