How The Simple Machines Upgrade Process Works?

Advanced users could be interested in the format used by SMF to provide upgrades. Actually, it's a kind of XML version of a patch, that is interpreted and executed in the local installation, by the SMF core implementation. This way, contrary to main forum softwares, the administrator does not need to do any file management (with all risks he can encounter, like FTP problems, files omitting, copy/replace problems,...) to update its installation.

The patch content is always provided inside a ZIP file, that is automatically unzipped by the Simple Machines local installation.

For this example, we have detailed the latest SMF patch, that migrates a SMF release from 1.1.10 to 1.1.11 (1.1 branch), and 1.0.18 to 1.0.19 (1.0 branch): smf_patch_1.0.19_1.1.11.zip, that could be downloaded here: SMF Upgrades.

Simple Machines Package Content

The Package Descriptor: package-info.xml.

<?xml version="1.0"?>
<!DOCTYPE package-info SYSTEM "http://www.simplemachines.org/xml/package-info">
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 This is a simplified package manifest for SMF packages.
 ATTENTION: If you are trying to install this manually, you should try
 the package manager.  If it will not work for you, please take a look
 at the following for information on this format:
  <a href="http://mods.simplemachines.org/docs/manual-install.php<br />
" title="http://mods.simplemachines.org/docs/manual-install.php<br />
">http://mods.simplemachines.org/docs/manual-install.php<br />
</a> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
 
<package-info xmlns="http://www.simplemachines.org/xml/package-info" 
                 xmlns:smf="http://www.simplemachines.org/">
 <id>smf:smf-1.1.11</id>
 <name>SMF 1.0.19 / 1.1.11 Update</name>
 <version>1.0</version>
 
 <type>modification</type>
 
 <install for="1.1.10">
  <readme type="inline">
   This patch file will update your forum to SMF 1.1.11.
  </readme>
  <modification type="file" format="boardmod">smf_1-1-10_to_1-1-11_patch.mod</modification>
  <modification type="file" format="xml">smf_1-1-11_can_fail.xml</modification>
 </install>
 <install for="1.0.18">
  <readme type="inline">
   This patch file will update your forum to SMF 1.0.19.
  </readme>
  <modification type="file" format="boardmod">smf_1-0-18_to_1-0-19_patch.mod</modification>
 </install>
 <uninstall for="1.1.11">
  <readme type="inline">
   This will downgrade your forum back to SMF 1.1.9.
  </readme>
  <modification type="file" format="boardmod" reverse="true">smf_1-1-10_to_1-1-11_patch.mod</modification>
  <modification type="file" format="xml" reverse="true">smf_1-1-11_can_fail.xml</modification>
 </uninstall>
 <uninstall for="1.0.19">
  <readme type="inline">
   This will downgrade your forum back to SMF 1.0.18.
  </readme>
  <modification type="file" format="boardmod" reverse="true">smf_1-0-18_to_1-0-19_patch.mod</modification>
 </uninstall>
</package-info>

The first <id>, <name> and <version> tags describe the package content, and they are used to inform the users
about what he is going to install on its local installation of Simple Machines. The <type> helps the SMF system to determine
what is needed to process the package, even if, actually, only the modification value is used.

Most important parts of the descriptor are the next instructions listed in the example above: <install> and <uninstall>. Depending on the release
you have installed on your Simple Machines bulletin board, the action will be different. Using the for attribute, SMF will be able to know which files will be applied.
For instance, if the local SMF installation version is 1.1.10, then the two files (from the ZIP package) smf_1-1-10_to_1-1-11_patch.mod and smf_1-1-11_can_fail.xml will
be applied.

Using this XML format, the Simple Machines is able to provide a central ZIP package that contains all updates required, potentially for all existing versions of SMF. Fortunately, this is not
a big piece of work, because upgrades are incremental and because the SMF team is only maintaining two active branches, SMF 1.0 and SMF 1.1. The SMF 2.0 branch will be enabled later, as it does not
required any patch, because no official versions (different from release candidates and betas) have released so far. More over, using this smart format, it is possible to revert an update
or a modification as well, that is really useful when something went wrong during installation or if you are experiencing weird problems after an upgrade. This kind of rare features really deserves to be notified.

The Patch file: smf_1-1-10_to_1-1-11_patch.mod.

 <edit file>
 $boarddir/index.php
 </edit file>
 
 <search for>
 * Software Version:           SMF 1.1.10  *
 </search for>
 <replace>
 * Software Version:           SMF 1.1.11  *
 </replace>
 
 <search for>
 $forum_version = 'SMF 1.1.10';
 </search for>
 <replace>
 $forum_version = 'SMF 1.1.11';
 </replace>
 
 
 <edit file>
 $sourcedir/BoardIndex.php
 </edit file>
 
 <search for>
 * Software Version:           SMF 1.1     *
 </search for>
 <replace>
 * Software Version:           SMF 1.1.11  *
 </replace>
 
 <search for>
 * Copyright 2006 by:          Simple Machines LLC (<a href="http://www.simplemachines.org" title="http://www.simplemachines.org">http://www.simplemachines.org</a>) *
 </search for>
 <replace>
 * Copyright 2006-2009 by:     Simple Machines LLC (<a href="http://www.simplemachines.org" title="http://www.simplemachines.org">http://www.simplemachines.org</a>) *
 </replace>
 
 <search for>
     'collapse_href' => isset($row_board['canCollapse']) ? $scripturl ...
 </search for>
 <replace>
     'collapse_href' => isset($row_board['canCollapse']) ? $scripturl ...
 </replace>
 
 <edit file>
 $sourcedir/Display.php
 </edit file>
 
 <search for>
 * Software Version:           SMF 1.1.9   *
 </search for>
 <replace>
 * Software Version:           SMF 1.1.11  *
 </replace>
 
 <search for>
 function Download()
 {
  global $txt, $modSettings, $db_prefix, $user_info, $scripturl, $context, $sourcedir;
 </search for>
 <replace>
 function Download()
 {
  global $txt, $modSettings, $db_prefix, $user_info, $scripturl, $context, $sourcedir, $topic;
 </replace>
 
 ...

This part is really easy to understand. This file is a series of <edit> tag, that define the file to modify,
that is followed by a <search for> tag, describing what is going to be replaced, and a <replace> tag
that contains the replacement for the <search for> content. You can notice that applying and reverting a patch could
be done with this format, as search for and replace could be inverted to cancel changes.

Ignored Modification Errors: smf_1-1-11_can_fail.xml.

 <modification xmlns="http://www.simplemachines.org/xml/modification" xmlns:smf="http://www.simplemachines.org/">
  <id>smf:smf-1.1.11</id>
  <version>1.0</version>
 
  <file name="$sourcedir/ManageRegistration.php" error="skip">
   <operation error="ignore">
    <search position="replace"><![CDATA[
 * Copyright 2006-2007 by:     Simple Machines LLC (<a href="http://www.simplemachines.org" title="http://www.simplemachines.org">http://www.simplemachines.org</a>) *
 ]]></search>
    <add><![CDATA[
 * Copyright 2006-2009 by:     Simple Machines LLC (<a href="http://www.simplemachines.org" title="http://www.simplemachines.org">http://www.simplemachines.org</a>) *
 ]]></add>
   </operation>
   <operation error="ignore">
    <search position="replace"><![CDATA[
 * Copyright 2006 by:          Simple Machines LLC (<a href="http://www.simplemachines.org" title="http://www.simplemachines.org">http://www.simplemachines.org</a>) *
 ]]></search>
    <add><![CDATA[
 * Copyright 2006-2009 by:     Simple Machines LLC (<a href="http://www.simplemachines.org" title="http://www.simplemachines.org">http://www.simplemachines.org</a>) *
 ]]></add>
   </operation>
  </file>
 
  <file name="$sourcedir/Packages.php" error="skip">
   <operation error="ignore">
    <search position="replace"><![CDATA[
 * Copyright 2006-2007 by:     Simple Machines LLC (<a href="http://www.simplemachines.org" title="http://www.simplemachines.org">http://www.simplemachines.org</a>) *
 ]]></search>
    <add><![CDATA[
 * Copyright 2006-2009 by:     Simple Machines LLC (<a href="http://www.simplemachines.org" title="http://www.simplemachines.org">http://www.simplemachines.org</a>) *
 ]]></add>
   </operation>
   <operation error="ignore">
    <search position="replace"><![CDATA[
 * Copyright 2006 by:          Simple Machines LLC (<a href="http://www.simplemachines.org" title="http://www.simplemachines.org">http://www.simplemachines.org</a>) *
 ]]></search>
    <add><![CDATA[
 * Copyright 2006-2009 by:     Simple Machines LLC (<a href="http://www.simplemachines.org" title="http://www.simplemachines.org">http://www.simplemachines.org</a>) *
 ]]></add>
   </operation>
  </file>
 
  ...
 
 </modification>

The SMF team has also added an additional security check in their package format. As usual, some patches
are not always working, for example if the local installation of Simple Machines has been modified directly,
or if some patches have not been applied in the good order, etc. Generally, if one of the instruction of
a patching process failed, the entire modifications should be reverted. However, using the smf_1-1-11_can_fail.xml
file, the Simple Machines local installation is able to understand is a chunk failed is important or not.

Now that the purpose of this file has been explained, it's quite easy to understand how it works: the main <file> tag
defines possible errors than can be skipped when this file is patched. Then each operation is atomically defined,
and the triggered action (skip, ignore,...) will be applied. If you look attentively, you will notice that contents of
<search> is equivalent to what was defined in <search for> tag of the smf_1-1-10_to_1-1-11_patch.mod, and
it's the same thing with <add> and <replace>/.

Advanced usage, the Upgrade process

You will maybe notice that the Package Info format also contains a specific tag, called <upgrade>, in addition to the
known <install> and <uninstall>. This tag is helpful when you are doing a major upgrade of your installation (for example, from
version 1.1 to the near 2.0 version). As usual, this kind of update is really more complicated, and it needs additional actions from the traditional patch).
Those actions are all described here:

<readme>
Display a Readme file.
<code>
Execute this PHP code.
<database>
Execute an SQL query.
<modification>
A Modification file to be applied.
<create-dir>
Create a new directory.
<create-file>
Create a blank file.
<require-dir>
Require a directory (and all files in it) from inside the package.
<require-file>
Require a file from inside the package.
<move-dir>
Move an entire directory.
<move-file>
Move a file from one place to another.
<remove-dir>
Remove an entire directory.
<remove-file>
Remove a file.
<redirect>
Redirect to a file or URL.

Goal of this article

We really hope that this explanation will help you to understand how plugins, patchs and updates work with the Simple Machines software. This huge work is also a proof about the quality of the SMF team, that could spend a lot of times on the upgrade process of existing SMF installations, rather than work on useless features that 1% of community administrators could be interested with.

It is reassuring to see that your current installation will be supported many years using this format, and it's really well, more particularly when you don't know what will happens in 2 years for some kind of forum softwares.

Next time, we will discover how the Simple Machines Theme Packages are working.

Get more information:

Keywords:
  Top Top