New MediaWiki software versions typically bring security fixes, performance enhancements, and new features. However, is updating your MediaWiki deployment to the latest stable release always advisable?
There are reasons why some wiki owners opt not to upgrade immediately. Common factors influencing this decision include:
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.
The current MediaWiki release policy delineates three distinct types of releases:
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.
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.
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 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 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 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.
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!
Here’s what we've been up to recently.
Explore the innovative integration of Large Language Models (LLM) like GPT into MediaWiki to enhance wiki functionalities. Our comprehensive blog discusses various integration methods, from API to direct hosting and extension development, alongside potential use cases.
From us to your inbox weekly.
We use cookies to provide and improve our services. By using our site, you consent to cookies.
Learn more
