New documentation: README.development.

diff --git a/doc/README.development b/doc/README.development
new file mode 100644 (file)
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 57b00c8d771d9aca783432a97dc998cfb93e9423..d381b15bf986c9784a04399a9153cb0b0706c820 100644 (file)
--- 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