There are different parts of XWiki that you may want to upgrade:

• Upgrading webapp
• Upgrading wiki documents
  • Let's clean it up

Upgrading webapp

The general strategy is to download the WAR distribution and to replace your current installed WAR. Make sure you don't copy on top since this could leave some old files around which would make XWiki fail (like if old JARs are lying around in WEB-INF/lib). 

Before replacing your current WAR, make sure you back it up, including configuration and data files.

Some additional operations may be required for upgrading and you must check the release notes for all the versions from the version you're upgrading from up to the new version you're installing. It's also possible that new features are available and that some configuration files need to be modified. If this is the case then it'll be specified in the release notes.

Note that the database schema is automatically upgraded when needed. All you need to do is to ensure your xwiki.cfg file is correctly configured to perform the migration. Here's a relevant excerpt from the xwiki.cfg file:

Upgrading wiki documents

You may want to upgrade to a newer version of the Default Wiki XAR in order to benefit from the latest changes. As mentioned above in the "Installing the Default Wiki XAR" section you should be very careful and when doing the import make sure you selectively decide what pages you wish to import. More specifically the following pages should be imported with great care:

• XWiki.XWikiPreferences: This page contains some configuration of your wiki (it overrides the configuration defined in xwiki.cfg). If you import a new version of this page you'll loose any customization you may have made such as the skin to use, the rights for your wiki, etc.
• XWiki.RegistrationConfig: Contains Registration configuration of your wiki.
• Invitation.InvitationConfig: Configuration for the Invitation Application.
• XWiki.WebPreferences, Main.WebPreferences, and all other spaces WebPreferences pages: Same as XWiki.XWikiPreferences but at the level of a space.
• XWiki.XWikiAllGroup (list of registered users) and XWiki.AdminGroup (list of Admins): If you have existing users and import a new version of these pages, you'll find that your users do not belong to these groups anymore and thus may not be able to edit pages, log in, etc. You'll need to add them again to the right groups.
• XWiki.Admin: This page contains the Admin user with the default password. If you import it you'll create a security hole. Thus it's very important not to import this page.
• XWiki.XWikiServerXwiki (multi wiki): This page contains the server descriptors, wiki properties.
• Any other page you have modified, such as Main.WebHome, a modified Panel, etc.

Let's clean it up

• Expand the XWiki WAR that you installed in your servlet container (the one that contains the JDBC drivers to access your database) into a new folder, using jar xvf xwiki-enterprise-web-3.1.war, or avoid this step if you performed an export/import data migration (you already expanded it) 
• Merge your old configuration files you have backed up (see above) with the new versions. Take care that if some changes were already made (probably because of database configuration when you installed the JDBC drivers) could be lost, so take care to add these changes
• Install this new folder as the xwiki application in your servlet container (may be by copying the folder to the servlet filesystem space or by packing it in a WAR file and deploying it in the container's administration interface)

At this point all is set, you can experience your old wiki data over the new XWiki core!