merge from HEAD

Author: Richard Jones

doc/admin_guide.txt

@@ -2,7 +2,7 @@
 Administration Guide
 ====================
 
-:Version: $Revision: 1.15.2.2 $
+:Version: $Revision: 1.15.2.3 $
 
 .. contents::
 
@@ -163,6 +163,8 @@ Maintenance of Roundup can involve one of the following:
 2. `software upgrade`_
 3. `migrating backends`_
 4. `moving a tracker`_
+5. `migrating from other software`_
+6. `adding a user from the command-line`_
 
 
 Tracker Backup
@@ -255,6 +257,54 @@ moved using the above steps) then you'll need to:
 6. start the tracker web and email frontends on the new machine.
 
 
+Migrating From Other Software
+-----------------------------
+
+You have a couple of choices. You can either use a CSV import into Roundup,
+or you can write a simple Python script which uses the Roundup API
+directly. The latter is almost always simpler -- see the "scripts"
+directory in the Roundup source for some example uses of the API.
+
+"roundup-admin import" will import data into your tracker from a 
+directory containing files with the following format:
+
+- one colon-separated-values file per Class with columns for each property,
+  named <classname>.csv
+- one colon-separated-values file per Class with journal information,
+  named <classname>-journals.csv (this is required, even if it's empty)
+- if the Class is a FileClass, you may have the "content" property 
+  stored in separate files from the csv files. This goes in a directory
+  structure::
+
+      <classname>-files/<N>/<designator>
+
+  where ``<designator>`` is the item's ``<classname><id>`` combination.
+  The ``<N>`` value is ``int(<id> / 1000)``.
+
+
+Adding A User From The Command-Line
+-----------------------------------
+
+The ``roundup-admin`` program can create any data you wish to in the
+database. To create a new user, use::
+
+    roundup-admin create user
+
+To figure out what good values might be for some of the fields (eg. Roles)
+you can just display another user::
+
+    roundup-admin list user
+
+(or if you know their username, and it happens to be "richard")::
+
+    roundup-admin find username=richard
+
+then using the user id you get from one of the above commands, you may
+display the user's details::
+
+    roundup-admin display <userid>
+
+
 Running the Servers
 ===================