System upgrade

By Samuel, 15 June, 2023

In February, we finished a big milestone for the backend of https://www.4training.net. It was a lot of work and in the end there was no change visible from the outward - probably normal for backend work ;-)

But under the hood we could change some important parts of the architecture. With them in place we’re ready for the next development steps! Here’s what happened:

Update to mediawiki 1.39 LTS

We updated the underlying mediawiki system to the current long-term support release. One basic reason is of course the fact that the previous mediawiki 1.35 LTS would turn end-of-life later this year. But besides the necessity to stay up to date, this release provided an important new feature: It’s the first LTS version with all parts of the new skinning system in place! That was already introduced in 1.35, but some parts of it where added only in the following releases. Now it seems to be completed and stable - finally we can use it.

Using composer to manage mediawiki installation

Before we had our own git repository to manage our installation. It was based on the mediawiki core repository, together with more git submodules for the extensions we also used. However, doing updates was always tedious. Somehow working with a lot of git submodules isn’t very intuitive and fun.

Now we switched to using composer as the de-facto standard for package and dependency management in PHP to manage our mediawiki installation. Our core repo is now small and clear, with a custom script to build the whole installation. We use patches in (few) cases where we make customizations to mediawiki core and continue to maintain some forks of extensions with little customizations. It feels much easier to work with this approach now with the safety net of being able to quickly switch to a previous version if something goes wrong. This comes with the cost that running the build script takes several minutes as more than 1 GB of files will be installed, but that’s something I can get used to.

Unfortunately mediawiki has still not made a decision for using composer as standard for package and dependency management. But many extensions come already with a composer.json in place and others are also using composer for their mediawiki installations, so it’s doable.

Migrate skin to Mustache

The legacy mediawiki skinning system involved writing quite some PHP with HTML code in between. My first approach was to just leave our legacy skin as it is and don’t bother with this extra topic. Theoretically that should still be supported in mediawiki 1.39. But after investing several hours into fixing the various PHP errors and warnings it still wasn’t running smoothly. It felt like this could suck up an unpredictable amount of more hours so I abandoned the approach and decided to migrate to the new skinning system.

The new skinning is based on mustache, a clever approach to templating and something what front-end developers nowadays expect (no ugly mixing of PHP code with HTML design anymore…)

I’m not a front-end developer and doing the migration was not my favorite task, but I fought my way through it. I came to like mustache: it’s simple yet powerful and its design of not having anything like if/else is smart.

I looked at the migration guide and decided to leave most of HTML and CSS as it was. As promised writing PHP code was only necessary for some logic customizations (e.g. extra stuff that is only loaded for logged-in users). See yourself in the new mediawiki-skins-ForTraining repository :)

So from the outside the site still looks the same and old-fashioned. We still need someone to make it look better and more mobile-friendly. But now we have prerequisites in place so that a front-end developer can work efficiently so I hope we’ll soon be able to move forward in this area as well.

Set up a proper test system

Our new central repository now has a main branch (deployed to www.4training.net) and a test branch (deploying to test.4training.net). After the migration to composer the repository is small and clear, so working with it is fairly easy. Now we have a properly set-up test installation that will be used not only for testing from a technical perspective, but also for developing and testing worksheets.

Using software development principles in developing teaching resources

It’s my vision to use principles of good software development in the area of developing training materials. Our source code is the content of the worksheets we provide. We have them in a “version control system” (mediawiki), apply semantic versioning, clarify our licensing conditions (all are “open source”, licensed under CC0: Creative Commons Zero), deliver updates with improvements, and have some quality assurance by testing our alpha / beta versions and release candidates.

I have been developing this work style over the past years and now having a proper test system will make it even more clear and intuitive.

Comments

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.