From: Michael Orlitzky Date: Sun, 15 Jun 2014 01:06:59 +0000 (-0400) Subject: New documentation: README.development. X-Git-Tag: 0.0.6~206 X-Git-Url: https://gitweb.michael.orlitzky.com/?a=commitdiff_plain;h=43d1e1035dc7d5d5cea5576b6b5cf0d9415438fa;p=dead%2Fhtsn-import.git New documentation: 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: IRL - Firestone 600 - Final Results + 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