MediaWiki Upgrades

MediaWiki updates bring security fixes, enhanced performance, and new features. Yet, is it always wise to upgrade to the latest stable version?

...
WikiTeq
Share:

There are reasons why some wiki owners opt not to upgrade immediately. Common factors influencing this decision include:

  • Fear of potential disruption
  • Concerns about breaking existing functionality
  • Contentment with the version they run

These apprehensions and concerns are not groundless. Open-source software, in general, and MediaWiki, in particular, continually evolves, introducing new approaches, deprecating old methods, and rewriting code. Before initiating a MediaWiki update, one must consider the compatibility of the new version with other software and the hosting environment, potential breaking changes in the code, and the availability of specialists with the required technical expertise to execute the upgrade and address potential issues.

For wikis accessible to the public, satisfaction with the currently deployed older version may become a false friend, exposing the wiki to exploits of known vulnerabilities.

Given the aforementioned considerations and budget constraints, you need a well-thought-out upgrade policy tailored to your wiki's use case, size, mission-criticality, and the extent of customization.

Establishing a MediaWiki Upgrade Policy

The current MediaWiki release policy delineates three distinct types of releases:

  • A minor or "point" release is issued approximately every quarter, encompassing security patches, back-ported message translations, and general bug fixes. Examples of minor releases include MediaWiki 1.39.4 and MediaWiki 1.39.5.
  • Major releases occur approximately every six months. These releases may include changes necessitating a database structure upgrade or configuration review, and they have the potential to break outdated extensions. Examples of major releases are MediaWiki 1.39 or MediaWiki 1.40.
  • Long-Term Support releases (LTS) are major releases launched every two years, with a one-year overlap in LTS support. For instance, 1.35 LTS reaches its end-of-life in November 2023, one year after the release of the 1.39 LTS. Long-term support releases receive security and bug fixes throughout their entire life cycle.

MediaWiki employs plugins to enhance its functionality, commonly referred to as "extensions." While some are officially supported and maintained by the Wikimedia Foundation, others are developed and maintained by various individuals or organizations with varying levels of commitment. These contributors may be occupied, less active, or concentrating on different priorities. Consequently, extensions have the potential to become abandoned, outdated, divergent from the MediaWiki core code, or superseded by newer alternatives.

If you're using a vanilla MediaWiki installation without extensions or with the default set of bundled extensions, adopting a policy of regular updates to both minor and major releases can be appropriate.

It's important to note that, starting from version 1.36, MediaWiki commits to supporting upgrades only from the two most recent LTS releases. Upgrades from older versions of MediaWiki will need to be executed in multiple steps. For those who have embraced the policy of minor wiki upgrades, the general recommendation is to proceed with an upgrade each time a new minor or major release becomes available, provided they adhere to the best practices listed below.

Developed to power Wikipedia, the out-of-the-box features of MediaWiki may differ from what is needed for your specific wiki use case. Many owners of MediaWiki sites desire a customized appearance and functionality to meet their unique requirements. Due to the MediaWiki flexibility and extensibility, it can be achieved through the community maintained or custom skins and extensions. However, it will affect the upgrade policy.

The workflow for releasing extensions operates independently of core releases. Each extension can establish its own compatibility policy. Some extensions commit to maintaining backward compatibility with major releases, while others may align with the version of the core major release. It's quite common for extension maintainers to prioritize compatibility only with LTS releases. In reality, major releases every six months often introduce changes that can potentially disrupt the functioning of the extension you are using. The resolution of issues by upstream developers can significantly postpone the process of upgrading to a major release, making it a cumbersome task.

If you have made customizations to your MediaWiki installation, document them thoroughly. This includes any changes to the skin, templates, or other aspects of the software. It will help modify your custom code as needed to align with changes in the MediaWiki codebase.

If you are managing a customized instance of MediaWiki, it is recommended to adhere to the LTS release cycle and skip non-LTS major upgrades. Instead, focus on applying point backports to the LTS version currently in use. This approach guarantees the security and stability of your production environment, providing the opportunity to plan and execute the next LTS upgrade effectively. With approximately one year of LTS release overlapping, you have ample time to address extensions compatibility issues.

Of course, you are free to choose any other policy in accordance with your wiki mission, commitments and budgets.

Best Distribution System for Frictionless Upgrades

There are various distribution systems for delivering upgrades to the MediaWiki core and extensions. The decision regarding the most suitable distribution system is crucial when initiating a MediaWiki-based project.

Archives or tarballs

The default method for the MediaWiki core and the majority of extensions. One can download a zip or tar archive from the official site or using the extension distributor, or via command line:

wget https://releases.wikimedia.org/mediawiki/1.40/mediawiki-1.40.1.tar.gz
Using Extension Distributor for getting the MediaWiki tarball.

Using Extension Distributor for getting MediaWiki

In this paradigm, the process for upgrading involves extracting the archive content and replacing the target directory. 

It looks simple and can be done using an FTP client, but please do not forget that after running the database upgrade using the web or command line interface, MediaWiki may require running maintenance scripts or updating composer-managed dependencies from command line.

Git

Git is a distributed version control system commonly used for tracking changes in source code during software development. MediaWiki core and most of the extensions store their code in git-based repositories.

Downloading from Git is recommended for MediaWiki instances under active development or customization. With a single command you can get the full tree of branches and commits, or pull the exact branch or commit. For example, to install MediaWiki 1.39, run:

git clone https://gerrit.wikimedia.org/r/mediawiki/core.git --branch REL1_39 mediawiki

A minor upgrade to the MediaWiki 1.39.5 is as simple as:

# Get the recent code
git pull 

# Open repository at a given tag
git checkout 1.39.5

# Upgrade bundled extensions or other extensions added as submodules
git submodule update --init

The similar procedure applies when updating individual extensions cloned from Git, just select a corresponding branch or tag to checkout.

# List all available branches
git branch -a

# List all available tags
git tag –list

# Upgrade Extension:ContactPage for use with Mediawiki 1.39
cd extensions/ContactPage
git checkout REL1_39

Like many command-line tools, upgrades through Git are simple and powerful. However, they necessitate a comprehension of Git fundamentals and familiarity with the MediaWiki administration and maintenance workflow.

Please note that when you get extensions as archives, using the extension distributor, necessary dependencies come with the archive. When you get software from git, MediaWiki core and certain extensions may require composer - a dependency manager for PHP - to install the dependent libraries and packages. 

Installation and update of the MediaWiki and the extensions with dependencies managed by composer will require running:

composer update --no-dev

When you make a decision to use a given extension, check its documentation page on mediawiki.org to learn about its compatibility policy, mandatory use of composer and/or database changes involved. 

Docker

Docker is a platform designed to provide a standardized way to package and distribute applications, ensuring consistency across different environments. You can think of Docker as of ready to use environment optimized to run MediaWiki and any of extensions included in the Docker image.

WikiTeq maintains Taqasta – a full-featured MediaWiki stack for easy deployment of enterprise-ready MediaWiki on production environments. Taqasta is bundled with over 100 well tested extensions. To upgrade of the whole stack you just need to change the image tag in the `docker-compose.yml` file:

- image: ghcr.io/wikiteq/taqasta:1.35.8
+ image: ghcr.io/wikiteq/taqasta:1.39.5

followed by:

docker compose up -d

In a few minutes, your MediaWiki and extensions will be upgraded to the requested version. Docker-based deployments handle various administration and maintenance tasks, offering a convenient solution for those seeking a stable and efficient environment at a lower cost and with minimal hassle.

Understanding of Docker is required or can be outsourced.

Best Practices for Performing MediaWiki Upgrades

Review System Requirements
Confirm that your server environment meets the system requirements for the new version of MediaWiki. This includes PHP, MySQL, or other database requirements. Please note, that if you go with the Docker image like Taqasta, it already comes with the correct versions of PHP, MySQL and other software needed to rum MediaWiki.
Monitor Resource Usage
Assess the resource requirements of the new MediaWiki version to ensure your server can handle the increased demands. This includes considerations for CPU, memory, and disk space
Review Release Notes
Thoroughly read the release notes for the version you're upgrading to. This includes information on new features, changes, and any potential incompatibilities with existing extensions or custom code.
Be aware of any features that are deprecated or removed in the new version. Adjust your custom code or configurations accordingly to avoid issues during or after the upgrade.
Examine your LocalSettings.php file for any deprecated settings or changes in configuration options. Update the configuration file accordingly.
Check Extension and Skin Compatibility
Verify that your installed extensions are compatible with the new version of MediaWiki. Some extensions may require updates or replacements to work with the latest release. If you use third-party extensions or skins, make sure they are updated to versions compatible with the new release of MediaWiki. Check the official extension and skin pages for compatibility information.
Prepare for Downtime
Major upgrades may require some downtime for your wiki. Plan for this, communicate it to your users, and choose a suitable time for the upgrade to minimize disruptions.
Prepare a rollback plan in case the upgrade encounters unforeseen issues. Knowing how to revert to the previous version quickly can help minimize downtime.
Backup Your Data
Always create a comprehensive backup of your MediaWiki database and files before initiating the upgrade. This ensures that you can revert to the previous state in case anything goes wrong.
Test in a Staging Environment
Set up a staging or testing environment that mirrors your production environment. Test the upgrade process, extensions, and customizations in this environment before applying changes to the live site.
Schedule the Upgrade
Choose a suitable time to perform the upgrade, considering the least impact on your users. Communicate the scheduled maintenance to your community.

No matter what policy you have adopted, consider keeping to the above rules and approaches to increase the likelihood of a successful MediaWiki update with minimal disruptions to your wiki's functionality.

WikiTeq has many other blogs to help you on your journey to become a MediaWiki professional. We recommend taking a look at our Introduction to Extensions and The Best MediaWiki Extensions

Do not hesitate to reach out to us for a free consultation if you need professional help with your MediaWiki Upgrade!

Latest Stories

Here’s what we've been up to recently.


Stay informed!

Get our latest blogs and news delivered straight to your inbox.