Upgrading

Warning

Pootle 2.6.1 is just an intermediate upgrade step towards newer releases.

Pootle 2.6.1 is meant to be only used as an intermediate step for upgrading older Pootle deployments to the newer Pootle releases.

Here are some points to take into account while performing Pootle upgrades.

Warning

Upgrading Pootle to a newer version can be a dangerous endeavour, so please:

  • Carefully read this entire page before proceeding with any further steps
  • Do all the recommended backups
  • Try to follow these instructions as must as possible

This page is divided in three sections. The first one lists some previous tasks that should be performed before upgrading. The second section includes a detailed list of steps to actually perform the upgrade. The third one tells you how to continue with the upgrade to the next version, since Pootle 2.6.1 is only an intermediate upgrade step.

Previous tasks

Note

If you perform all the steps in this section you will:

  • Avoid losing any data or Pootle customizations,
  • Ensure a thorough and successful upgrade,
  • Prevent headaches for you and the support team.

Before upgrading Pootle to a newer version, make sure to go through this checklist.

  • Familiarize yourself with important changes in Pootle over the versions.
  • If you want to change the database backend then have a look at the database migration page first. We discourage using SQLite, so if you are using it please migrate to a real database server.
  • Ensure that you meet all the hardware requirements for the newer version.
  • Always make backups of all your translation files (your whole PODIRECTORY). Use the sync_stores command to synchronize to disk all your translation files before making any backup.
  • Also backup your settings, to avoid losing any settings customization.
  • Make a backup of your complete database using the appropriate dump command for your database system. For example mysqldump for MySQL, or pg_dump for PostgreSQL.
  • And don’t forget to backup any code, templates or styling customization that you have done to your Pootle.
  • You might want to look for any new available settings in the new version that you might want to configure.

Upgrading

Here is the list of steps to upgrade a Pootle install using the pip tool.

Note

Since these instructions don’t take into account other possible installation methods, like using a checkout from git, you will have to do the appropriate adjustments in this list if you didn’t install Pootle using pip.

Warning

Always backup the following before upgrading:

  • the entire database
  • all the settings
  • all your translation files
  • any code customizations
  • any templates customizations
  • any styling customizations

To perform the upgrade follow the next steps:

  • If you want to perform a database migration then do it right now.

  • It is highly recommended to use a virtualenv, so if you don’t use it please set up a virtualenv.

  • Upgrade the Pootle package:

    (env)$ pip install --upgrade Pootle==2.6.1
    

    Note

    If you weren’t using a virtualenv before upgrading, instead of upgrading you will be just doing a fresh install of Pootle in a blank virtualenv:

    (env)$ pip install Pootle==2.6.1
    
  • Update Pootle settings to include new useful settings and updating existing ones, while keeping the necessary data from the old install. Deleting now unused settings is also advisable. Check the available settings.

    Note

    If you are upgrading from a version of Pootle that uses localsettings.py then you must move your custom settings to a new location in order to ensure that Pootle uses them.

  • Perform the database schema and data upgrade by running:

    (env)$ pootle setup
    

Continue the upgrade to a newer version

Since Pootle 2.6.1 is intended to be an intermediate upgrade step towards newer Pootle releases you will have to upgrade again to the desired version. In order to do that just follow the upgrade instructions for that version.

Warning

Please note that if you have some custom changes to Pootle code, templates or styling you will have to reapply those after finishing the upgrade to the desired Pootle version. Instructions on how to do that are available on the upgrade instructions.