Add a README

README.md

+# osqa-to-askbot
+
+This project allows you to migrate content from an [OSQA][osqa] instance to
+[AskBot][askbot]. It was made for the migration of [Chiedi][chiedi] (by
+Ubuntu-it), so it might not migrate everything for your website in the way you
+want, and it currently supports only PostgreSQL.
+
+osqa-to-askbot is released under the GNU GPLv3+ license.
+
+
+## Why this project?
+
+AskBot provides a [way to migrate data from OSQA][askbot-migrate], and for
+small websites you can use it without any issues.
+
+The problem is, that script requires you to dump all the OSQA data in one file,
+and then it loads it in memory and migrates the data. Our database weights
+about 4GB though, and loading all of it into memory is not easily doable.
+
+osqa-to-askbot takes a different approach: it connects to the live OSQA
+database, then it loads a small chunk of data and migrates it. This allows to
+migrate huge databases without worrying about going out of memory.
+
+osqa-to-askbot also skips already-migrated data, so you can run the migration
+multiple times on the same database if you want to reduce the maintenance
+window, by doing a full migration in the background and then other small
+incremental migrations to catch up with the latest changes.
+
+
+## Usage
+
+osqa-to-askbot requires a (read-only) connection to the production database of
+OSQA, and the instance of AskBot you want to migrate to. AskBot must be
+installed already, but you should not create any user nor question if you don't
+want to have any conflicts (the IDs are kept from OSQA to AskBot).
+
+First of all you need to install the tool in a Python 2 virtualenv:
+
+```
+$ git clone http://code.ubuntu-it.org/ubuntu-it-ask/osqa-to-askbot.git
+$ virtualenv -p python2 env
+$ env/bin/pip install ./osqa-to-askbot
+$ rm -rf osqa-to-askbot
+```
+
+Then you can call the tool:
+
+```
+$ env/bin/osqa-migrator "dbname=OSQA_DATABASE" /PATH/TO/APP /PATH/TO/ASKBOT/ENV
+```
+
+In the command above, you need to replace:
+
+* `OSQA_DATABASE` with the name of the OSQA database. The quoted string is a
+  [psycopg2][psycopg2] connection string, so if you need to connect to a remote
+  database you can customize it.
+* `/PATH/TO/APP` with the path of your AskBot installation
+* `/PATH/TO/ASKBOT/ENV` with the path of the Python environment in which AskBot
+  was installed. If you installed AskBot globally it's the system Python prefix
+  (you can get it with `python2 -c "print __import__('sys').prefix"`)
+
+After you migrated all your data, simply remove the tool's virtualenv:
+
+```
+$ rm -rf env
+```
+
+[osqa]: http://www.dzonesoftware.com/products/open-source-question-answer-software
+[askbot]: https://askbot.com
+[chiedi]: http://chiedi.ubuntu-it.org
+[askbot-migrate]: https://github.com/ASKBOT/askbot-devel/blob/master/askbot/management/commands/askbot_add_osqa_content.py
+[psycopg2]: http://initd.org/psycopg/