Upgrading to a New Version
From Textbook
Here we describe how to manually upgrade your existing Textpattern installation to the latest, stable release (currently 4.2.0). In a nutshell, what you will be doing is backing up your current installation, overwriting your existing installation with the new package, updating your Language Preferences, and addressing any problems indicated in Diagnostics.
If you are knowledgeable of Subversion and would rather go that route, see the SVN options under the Installation topics.
Contents |
Step 1: Get the New Package
Go to textpattern.com/download and download the zip package of the latest version (currently 4.2.0) to your local machine. Unzip the package into a folder on your local drive. Give the folder a meaningful name like txp-4.2.0, for example.
Step 2: Backup (to be Safe)
As with any system upgrade, you'll want to be sure you can fall back on your existing install should there ever be a problem; thus, you should back up your server files and create a database dump file (.sql) before upgrading.
Duplicate the Existing Txp File Tree
Make a copy of the current system file tree (folders and files of the Textpattern installation). The easiest way to do this is to log onto the server using FTP or SFTP (sometimes required by certain hosts), create a new folder called txp-current, for example, and copy the existing system file tree into this new folder (leave the file tree structure the same).
Create a Database Dump File (an .sql export)
Log in to the phpMyAdmin database administration panel for your site (different web hosts have different access routes), and then follow these steps:
- Select the database running the current Textpattern site from the left column.
- In the resulting main content area, click Export at the top of the screen.
- You should be able to use the defaults as they already are, just make sure you tick the Save as file box at the bottom of the screen.
- Click Go button.
The .sql dump file will mostly likely be saved to your desktop. Using FTP/SFTP again, copy the file into the backup folder you just created to keep everything together.
You now have a full backup of your files and database. If things don't work out in the upgrade process, you can simply replace the server files and, if necessary, re-import the old database dump file in phpMyAdmin again (using Import instead of Export). If you do have problems, you might consider running a development (sister) site of your main site and try upgrading there first.
Step 3: Install the New Textpattern Files
Using FTP/SFTP again, navigate to the folder you created in step 1 and copy the new files from there to the original location on your server, overwriting the old installation files.
Then copy your existing config.php from the /textpattern/ folder in the folder you created in step 2 to the new /textpattern/ folder in the original location on your server.
It is important that you make sure all three index.php, css.php and .htaccess files transfer over. This shouldn't be a problem, but sometimes in the case of the .htaccess file it does not show up in certain FTP clients (it's usally there but just not visible). In the case of the .htaccess file, if you had any customizations (such as mod_rewrite changes), be sure to add them back to the top of the new file so you don't lose that functionality. When in doubt, compare your backed-up copy of the file against the new one.
Step 4: Update
Open a web browser and go to the Admin-side location. Log in if necessary. That's it. Easy, huh? There are no update scripts to run or anything else; by simply going to the normal admin-side location on the new files, Textpattern will recognize the need to update and do so automatically.
Step 5: Fine-tune
When Textpattern updates, you will be taken by default to Language Preferences. Once there, update your chosen language files as necessary (highlighted with orange backgrounds). Then go to the Diagnostics tab and troubleshoot any issues noted in red text.
Some red-text notices are not always problems, per se, but may only appear to indicate some difference in the system since your upgrade. When in doubt about an error message, first check Diagnostics to see if it's documented, if that doesn't help, ask in the How do I... forum.
Step 6: Remove Unnecessary Files
After installing or upgrading Textpattern, you only need to delete the setup folder (.../textpattern/setup). This folder and it's contained files are not used once Textpattern is installed. (If you do not do this before checking your Diagnostics in step 5, you'll see a diagnostic error reminding you to do it. The error will disappear when the folder is removed.)
The setup folder is only used for new installations, not upgrades, thus it's technically not necessary to add this folder from the latest, stable package. However, don't go out of your way to be clinical, simply upgrade using the full package and then delete the folder afterwards. It's easier all-around.
Step 7: Debugging check
This step is highly recommended, but optional. It is best to do this on a development server to avoid showing your users error messages. Alternately, put your site into maintenance mode, using the rvm_maintenance plugin.
Change your site's Production Status to "debugging". Go through the live site (every page, if possible), looking for error messages. Any such messages will be clearly visible at the top of the page. The upgrade may result in notices or errors relating to deprecated tags or attributes. These should be easy to correct.
If you do need to update tag or attribute names, the smd_where_used plugin is a great help for quickly finding all instances of a given tag or attribute.
