This is an example of upgrading XWiki from e.g. version 3.1 to version 3.2

==== 1. Prepare directory structure ====
 * Login to XWiki server via putty (0.0.0.0, user, password)
 * Go to ##/home/xwiki-upgrade##
 * Create folder ##migration-3.1-3.2##
 * Create following subfolders
    ** ##./backup##
    ** ##./distr##
    ** ##./new_cfg##
    ** ##./old_cfg##
 * Copy ##/opt/apache-tomcat-6.0.29/webapps/xwiki## to ##/home/xwiki-upgrade/migration-3.1-3.2/backup##
 * Go to XWiki new release download page and find the link to download war-file from. In this case it was ##http://download.forge.objectweb.org/xwiki/xwiki-enterprise-web-3.2.war##
 * Go to ##/home/xwiki-upgrade/migration-3.1-3.2/distr##, run ##wget http://download.forge.objectweb.org/xwiki/xwiki-enterprise-web-3.2.war##
 * Run unzip on newly downloaded file to unzip it into ##xwiki## directory ##unzip xwiki-enterprise-web-3.2.war -d xwiki##
 * Copy following files to ##/home/xwiki-upgrade/migration-3.1-3.2/old_cfg##
    ** ##/opt/apache-tomcat-6.0.29/webapps/xwiki/WEB-INF/hibernate.cfg.xml##
    ** ##/opt/apache-tomcat-6.0.29/webapps/xwiki/WEB-INF/xwiki.cfg##
    ** ##/opt/apache-tomcat-6.0.29/webapps/xwiki/WEB-INF/xwiki.properties##
 * Copy following files to ##/home/xwiki-upgrade/migration-3.1-3.2/new_cfg##
    ** ##/home/xwiki-upgrade/migration-3.1-3.2/distr/xwiki/WEB-INF/hibernate.cfg.xml##
    ** ##/home/xwiki-upgrade/migration-3.1-3.2/distr/xwiki/WEB-INF/xwiki.cfg##
    ** ##/home/xwiki-upgrade/migration-3.1-3.2/distr/xwiki/WEB-INF/xwiki.properties##
    ** ##/opt/apache-tomcat-6.0.29/webapps/xwiki/WEB-INF/lib/mysql-connector-java-5.1.5-bin.jar##

==== 2. Merge configuration files ====
 * Login to XWiki server using winSCP
 * Download the ##new_cfg## and ##old_cfg## folders to your convenient location
 * Merge changes from ##old_cfg## files into corresponding ##new_cfg## files using IntelliJ IDEA "compare with clipboard" functionality. {{warning}}Please make sure that you dont merge any legacy lines from old configuration file which were removed in new configuration.{{/warning}}
 * {{info}}TODO: add descriptions which properties in which files were changed{{/info}}
 * Copy ##new_cfg## folder back to its server location (owerwriting the original files)
 
==== 3. Prepare libraries and their patches ====
 * No libraries are currently patched

==== 4. Prepare XWiki application package ====
 * Copy files from ##new_cfg## to their corresponding places in ##/home/xwiki-upgrade/migration-3.1-3.2/new_cfg##
    ** ##/home/xwiki-upgrade/migration-3.1-3.2/distr/xwiki/WEB-INF/hibernate.cfg.xml##
    ** ##/home/xwiki-upgrade/migration-3.1-3.2/distr/xwiki/WEB-INF/xwiki.cfg##
    ** ##/home/xwiki-upgrade/migration-3.1-3.2/distr/xwiki/WEB-INF/xwiki.properties##
    ** ##/home/xwiki-upgrade/migration-3.1-3.2/distr/xwiki/WEB-INF/lib/mysql-connector-java-5.1.5-bin.jar##

==== 5. Backup XWiki ====
 * Backup pages via export tool
 * Backup database with following command (((

{{code language="bash"}}
mysqldump --user=user --password=password --default-character-set=utf8 xwiki_db > Backup-YYYY.MM.DD-HHmm-xwiki_utf8_db-<comment-why-backing-up>.sql

{{/code}}
)))

==== 6. Stop server ====
 * run ##service tomcat stop##
 
==== 7. Backup tomcat files and clean directory ====
 * delete
    ** ##/opt/apache-tomcat-6.0.29/webapps/**xwiki**##
    ** ##/opt/apache-tomcat-6.0.29/work/Catalina/localhost/**xwiki**##
    ** ##/opt/apache-tomcat-6.0.29/logs/*.*##

==== 8. Install new application ====
 * move ##/home/xwiki-upgrade/migration-3.1-3.2/distr/xwiki## to ##/opt/apache-tomcat-6.0.29/webapps##

==== 9. Start server ====
 * ##service tomcat start##

==== 10. Import new xar ====
 * Download new XWiki *.xar file to your local folder
 * Login to application as root: Admin/trickyAdminPassword
 * Upload xar file to xwiki
 * Import new xar, but have the XWiki.Admin unchecked to avoid restoring Admin password

==== 11. Restore environment ==== 
===== Restore Admin password =====
If you have overwritten the XWiki.Admin, login with default ##Admin/admin## credentials and reset the admin password

===== Restore permissions ====
 * Forbid external users to 
    ** Register
    ** View content
 * Allow all groups to view XWiki (configured in admin wiki)
 * Restore users in Admin group.

===== Restore Mail configuration ====
Following are the proper settings for SMTP server

{{code language="properties"}}
admin.email= xwiki-update-notifier@mycompany.com
server = mail.mycompany.com
port = 25
{{/code}}

no password needed for this server.

===== Restore WYSIWYG settings ====
 * Plugins: ##color font justify##
 * Tool bars: ##| justifyleft justifycenter justifyright justifyfull | fontname fontsize forecolor backcolor | removeformat 

==== 12. Verify log files for errors ====
Location of the logs is ##/opt/apache-tomcat-6.0.29/logs/##