Add documentation for upgrade

2 files changed, 164 insertions, 0 deletions

diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..4a4301d
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,3 @@
+*.html
+INSTALL
+UPGRADE
diff --git a/docs/en/UPGRADE.t2t b/docs/en/UPGRADE.t2t
new file mode 100644
index 0000000..1e874fe
--- /dev/null
+++ b/docs/en/UPGRADE.t2t
@@ -0,0 +1,161 @@
+Chimère upgrade
+Étienne Loks
+Last update: %%date(%m-%d-%Y)
+%! Encoding: utf-8
+
++ Get new version of dependencies +
+
+++ From version prior to 1.1 to 1.1 ++
+
+Upgrade Django to the 1.2 version.
+
++ Get the new version +
+
+First of all get the new version of the code source.
+
+++ Download archive from the download site ++
+
+Versions are available at this [address http://www.peacefrogs.net/download/chimere/].
+Take care of getting the last version in the desired X.Y branch (for instance
+the last version for the 1.0 branch is version 1.0.2 as the time of writing of
+this document).
+Extract it to the desired destination path.
+
+```
+# wget http://www.peacefrogs.net/download/chimere -q -O -| html2text
+(...)
+[[   ]] chimere-1.0.0.tar.bz2     17-Nov-2010 16:51  53K
+[[   ]] chimere-1.0.1.tar.bz2     17-Nov-2010 16:51  53K
+[[   ]] chimere-1.0.2.tar.bz2     17-Nov-2010 16:51  53K
+(...)
+
+# wget http://www.peacefrogs.net/download/chimere/chimere-1.0.2.tar.bz2
+# mv chimere-1.0.2.tar.bz2 /var/local/django
+# cd /var/local/django
+# tar xvjf chimere-1.0.2.tar.bz2
+# cd chimere-1.0.2
+```
+++ Get from the Git repository ++
+
+Clone the Git repository, checkout the desired version and copy it to the
+desired destination path.
+
+```
+# git clone git://www.peacefrogs.net/git/chimere
+# cd chimere
+# git tag -l
+(...)
+v1.0.0
+v1.0.1
+v1.0.2
+# git checkout v1.0.2
+# cd ..
+# mv chimere /var/local/dgango/chimere-1.0
+# cd /var/local/dgango/chimere-1.0
+```
+
++ Copy files from your old installation +
+
+From your old installation at least copy "settings.py" and the content of
+"static/icons/" and "static/upload/" to the new installation.
+You have probably customised some styles and templates (for instance
+"styles.css", "welcome.html" and "base_user.html") don't forget to copy them and
+eventualy adapt them (if you have old vanilla version of this file comparing
+with the new one provided is easier).
+
++ Adapt settings.py +
+
+The format of settings.py could have evolved, the easiest way to complete your
+settings.py is to compare your old settings.py.example and the new one provided.
+
+++ Specific to upgrade from version 1.0 to version 1.1 ++
+
+Version 1.1 of Chimère uses Django 1.2 and with it the manner to define database
+has changed.
+
+Old way to define your database is:
+
+```
+DATABASE_ENGINE = 'postgresql_psycopg2'
+DATABASE_NAME = 'chimere'
+DATABASE_USER = 'chimere-user'
+DATABASE_PASSWORD = 'password'
+DATABASE_HOST = 'localhost'
+DATABASE_PORT = ''
+```
+
+The new one looks like:
+
+```
+DATABASES = {
+    'default': {
+        'NAME': 'ratatouille',
+        'ENGINE': 'django.contrib.gis.db.backends.postgis',
+        'HOST': 'localhost',
+        'PORT': '5432',
+        'USER': 'chimere-user',
+        'PASSWORD': 'password',
+    },
+}
+```
+
+Be careful to adapt properly your settings.py
+
++ Run migration scripts +
+
+Migration scripts test your installation before making changes so you probably
+won't have any lost but by precaution before running theses scripts don't forget
+to backup your database.
+You can also make a copy of your current database into a new database and make
+the new installation to this new database.
+
+If you run the migration scripts in a production environnement stop the old
+instance of Chimère before executing the migration script. Perhaps prepare the
+web server to point to the new installation before doing the database upgrade
+(cf. next paragraph).
+
+In "settings.py" verify that "chimere.scripts" is in the INSTALLED_APPS.
+
+After that in the chimere directory just execute the script:
+
+```
+python ./scripts/upgrade
+```
+
++ Point to the new installation +
+
+Most of the job is done. You'll just have to configure your web server to serve
+the new version.
+For instance for Apache the directive is changed from:
+```
+PythonPath "['/var/local/django/chimere/'] + sys.path"
+```
+To:
+```
+PythonPath "['/var/local/django/chimere-1.0.2/'] + sys.path"
+```
+
+Restart your web server and apart from web browser cache issues this should work.
+
++ Force the upgrade of visitor's web browser cache +
+
+If major changes in the javascript has be done between version, many of your
+users could experience problems. There are many tricks to force the refresh
+of their cache. One of them is to change the location of statics files. To do
+that edit your settings.py and change:
+```
+MEDIA_ROOT = ROOT_PATH + 'static/'
+MEDIA_URL = '/' + EXTRA_URL + 'static/'
+```
+To:
+```
+MEDIA_ROOT = ROOT_PATH + 'static/v1.0.2/'
+MEDIA_URL = '/' + EXTRA_URL + 'static/v1.0.2/'
+```
+Then in the static directory:
+```
+$ ln -s `pwd` v1.0.2
+```
+
+Restart the web server to apply changes.
+