DebianWiki/WikiRevamp

We are migrating the current Wiki to MediaWiki. The primary motivation is to migrate away from out-of-support technology (MoinMoin, Python2).

In DebConf25, a BOF was dedicated to discuss the state of the Debian Wiki. Known historical issues were summarized, in particular:

the wiki relies on old software
there are no clear guidelines on the scope of wiki content
there is no "default" license, most of the pages don't specify one and the few who specify use a number of them. As a consequence, most of the pages probably do not comply with DFSG
there is no clear way to handle communications about the wiki

Get Involved!

This is being worked on by ?AndrewSayers, Ceppo, SunilMohanAdapa, jmtd, MaythamAlsudany, TaaviVäänänen, GuillemJover, and perhaps, you!

Discussions take place on the debian-wiki@lists.debian.org mailing list, with live discussion in the #debian-wiki IRC channel. You're encouraged to follow both.

Current Plan

mass-edits to massage the current Wiki content as necessary for later steps
import MoinMoin database (full history) into Mediawiki with current page content (markup)
Get HTML rendering for all pages (possibly perform some post-processing)
Convert the HTML to Mediawiki via Pandoc (possibly perform some more post-processing)
Update every page on new wiki with the result of the above
Rename pages
Lock old wiki, new wiki is now Live; migrate hostname

Software migration

During the BOF, the possibility of a migration to MediaWiki was brought up, a well-established wiki platform already being used by many others like Wikipedia and the Arch Wiki.

Since then, @taavi has worked with DSA to setup mozart.d.o, a machine running Debian Trixie that hosts a MediaWiki instance. It can be accessed at https://wiki2025.debian.org/. Do not begin to migrate content here yet, it may be wiped without notice.

Currently, the plan is to migrate most pages to the MediaWiki instance using tools being developed by @guillem and @maytham, which will retain edit history as well as convert content to MediaWiki syntax as a final edit at the end. This is achieved by accessing the internal file-based database for MoinMoin. You can find a demonstration of this on FreedomBox (new wiki), where edit history has been retained.

Current resources for conversion:

@guillem: Debian fork of mm2mw Perl scripts for migrating with both history and syntax conversion
@maytham: shell scripts to retain history but without syntax conversion
@sunilmohan: https://salsa.debian.org/sunilmohan/moinmoin_to_mediawiki/ (based on a tool to generate the FreedomBox Manual PDF)
@AndrewSayers: mediawiki-recommendations (a counterpart to the recommendations page)

The configuration and extensions for the new instance have not been finalised yet. @maytham is working on an extension to provide the Debian navbar that is present on many other Debian sites. New extensions require manual intervention by DSA, which can take some time, especially if they are not packaged.

Content licensing

The migration provides a good opportunity to think about the long-standing licensing problems that mean content from the wiki cannot really be reused or redistributed legally.

Since 24 July 2025, new content on the existing wiki uses CC BY-SA 4.0 unless otherwise noted, so non-copyrighted work will gradually be replaced even without migrating.

The migration will most likely work like previous migrations between MoinMoin versions - the old edit history is retained, and a new edit updates the formatting. That ensures the migration to MediaWiki isn't blocked on the time-consuming process of rewriting content, but licensing issues will only fade away gradually over the years.

Choice of license

The Creative Commons Attribution-ShareAlike 4.0 license was agreed upon between participants in the mailing list and IRC because:

it is designed for and applies to content, rather than other licenses that are aimed at software.
requires attribution for contributors' hard work.
ensures any adaptations of the work remain CC BY-SA 4.0, preventing someone taking the work and making it proprietary.
relatively permissive and is compatible with GPL-3.

Why not public domain / CC Zero? The license chosen should generally require attribution. Virtually no content from other sources/sites could be copied to the wiki because nothing is compatible with public domain except other public domain content.

Why not Expat (MIT)? This license is intended for software. Licenses like the Creative Commons licenses were created specifically with non-software works in mind. Note that the Debian website (www.debian.org) uses this though.

Why not GFDL? In 2006, Debian Developers moved a General Resolution that concluded the GFDL is not a DFSG-compatible license, except when it is used without any of its invariant options. It is also much more restrictive, reducing the possibility of using wiki content elsewhere, like manual pages or official documentation.

Why not CC's NC or ND options? These are not DFSG-compatible.

Old content

@maytham is leading an ongoing relicensing effort to contact previous contributors and obtain permission for their work to be relicensed under CC BY-SA 4.0.

New content

Notices have been added to the current wiki so that any contribution submitted after 24 July 2025 00:00 UTC is released under the CC BY-SA 4.0, unless otherwise noted. A copyright.html page has also been written up with details on how to be compliant with the license

Recommendations and mass-edits

Before we can migrate the wiki, we need to identify all the ways it will behave differently, and work out how to convert those differences. For example, the current wiki has "discussion" pages that end with /Discussion and are linked from within the page body. The equivalent MediaWiki convention is for "Talk" pages to begin with Talk:, Category_talk: etc. and be linked from the menu above the page body. Rules and recommended processes are being written up in DebianWiki/WikiRevamp/Recommendations.

Several differences involve converting loose editing conventions to automated rules, by writing pattern-matching code and doing mass-edits to ensure every case matches the pattern. For example, "discussion" links are added by individual editors with page-specific styling, every instance of which will need to be removed during the migration. To achieve that, we plan to change all discussion links to supplementation page instructions that can be easily removed during the migration process. Tools for these conversions are available in the mediawiki-recommendations repository.

Specific mass-edits

A "mass-edit" is the process of editing many (usually tens or hundreds) of pages at once. Unlike normal edits, they are generally at least partially automated, and aimed at formatting issues instead of content. The term "mass-edit" is a reference to MediaWiki's MassEditRegex extension.

See /MassEditLog for a list of previous mass-edits.

Responding to a mass-edit

If you expect an upcoming mass-edit to affect a lot of pages you maintain, consider making a rule to ignore e-mails with the subject Update of ".*" by <author> and a date within the specified range, where <author> is the wiki name of the person doing the edit (e.g. AndrewSayers).

If you object to an upcoming mass-edit, contact the mailing list (preferably in a reply to the edit's thread) before the edit occurs, and explain your objection. We'll talk through the issue and look for suitable ways to change the upcoming edit. If you're having difficulty phrasing your objection, it's fine to just say "I need time to think through the implications, please postpone by a week", then write a longer reply a few days later.

If you object to a previous mass-edit, contact the mailing list (preferably in a reply to the edit's thread) after reverting the change, and explain your objection. We'll talk through the issue and look for solutions (e.g. a new mass-edit to fix other pages). Editors are usually notified about changes to pages they've edited, but a mass-edit that affects a thousand pages will generate notifications for all future changes to all thousand pages, so you shouldn't assume the mass-editor has seen your reversion.

Other conversations

$/!\$ This section attempts to summarise conversations from the mailing list and IRC channel. It will always be somewhat out-of-date and incomplete.

Debian Bug Links

The current wiki renders Debian and Ubuntu bugs specially - links get a title and closed bugs are struck through. For example, the following bugs should be struck through, and you should see a custom title when you hover over them: Debian Bug #399237 Launchpad bug 1597017.

This is implemented by including bugstatus.js in every page, which scans the HTML for appropriate links and sends requests to the bugstatus script and the launchpad script. The bugstatus script in turn uses the Debbugs SOAP interface, while the launchpad script uses launchpadlib.

MediaWiki alternatives to this solution include:

MediaWiki:Common.js is a JavaScript file included on every page in a wiki. This is the most direct translation, but can be hard to manage because of the temptation to put unrelated content in the same file.

The Gadgets extension is a more powerful alternative to MediaWiki:Common.js, and seems like the natural choice for a MediaWiki equivalent of the current implementation.

Scary Transcluding lets you include pages and templates from other wikis. Data is cached, with a configurable timeout. For example, this would let us run an internal service that generates HTML from some pre-existing Perl library, then transclude that HTML into ordinary wiki pages. It's the wrong tool for this particular job, but may be worth revisiting if other use cases pop up.

The Cargo extension lets MediaWiki store and query data in an internal database, which could potentially be synchronised with an external database somehow. But Cargo has a poor security reputation, and synchronising data could be awkward.

The External Data extension lets MediaWiki interrogate external sources like the Ultimate Debian Database. This would let us render links server-side instead of in JavaScript, but would introduce questions around caching. Allowing the wiki to query the UDD opens up a lot of interesting possibilities, and this might be a good way to make that possible. This is the solution we currently expect to use.

See also: DebianBug links on the mailing list.

Migrating user accounts

The plan is to switch from MoinMoin's built-in user database to Salsa accounts, so people will need to create a Salsa account.

The suggested solution is to disable creation of new wiki accounts at some point, give people Salsa accounts with the same username as the wiki, and ask them to change their information if they want.

See also: How to manage new Salsa accounts with the new wiki on the mailing list.

Boilerplate page headers

Pages often start with some boilerplate text (e.g. translation headers). Putting a common header template on all pages would make it easier to manage that text. See the PageHeader template for an initial demonstration.

This has been mentioned in passing, but no decision has been made.

Translations

We plan to install MediaWiki's Translate Extension to handle translation. Benefits of this extension include:

no need to maintain a 'TAG:TRANSLATION-HEADER' block - just add <languages /> to the top of the page, and the rest is handled automatically
- see e.g. the "Languages" block at the top of Translate Extension
provides advanced translation tools, like showing how complete a translation is and suggesting machine translations
may be familiar to people coming here from other MediaWiki-based wikis

We could avoid the need to add <languages /> by installing MediaWiki's Universal Language Selector Extension and enabling wgTranslatePageTranslationULS. To see how this works, go to Debian's Wikipedia page and click on the Languages button near the top of the page.

An alternative would be to write our own custom templates (see ExampleForTranslation). They would have no external dependencies and we could modify them more easily, but they'd be harder to maintain and wouldn't have as many features.

Another alternative is OpenStreetMap's languages template. This uses a Lua module, so it only requires the common Scribunto extension. It would probably produce a better result than custom templates, but doesn't provide the advanced tools in MediaWiki's solution.

We plan to include a template to link to localised versions of pages. So for example, if you're translating Page1 and find a link to Page2, {{ll|Page2}} will update automatically when translations of Page2 are added or removed - see MediaWiki's Localized link template, the custom ll template, and OpenStreetMap's LL template.

Editorial tasks (e.g. CategoryProposedDeletion)

In the current wiki, pages are added to editorial categories like CategoryProposedDeletion, with the expectation the editorial work will be made at some future date. That editorial process is discussed in the editor guide.

MediaWiki makes it easy to create more verbose and precise admonitions, with guidance on the page itself - see ExampleForProposedDeletion.

Scope

Discussion on the scope of the wiki is ongoing, but still in early stages. Most of it is happening in aims of the wiki? on the mailing list.

A draft for guidelines were published at MaythamAlsudany/DraftContentGuidelines and is open for discussion.

Milestones and gamification

By default, MediaWiki notifies you when you make round-numbered edits (1st, 10th, 100th etc.). This can be disable by going to event preferences and disabling "Edit milestone", but there doesn't seem to be a way to disable this by default for new users.

Automated edits with bots

We don't have bots making edits to the current wiki, but some proposals for the new wiki would benefit from automated edits.

Debian Bug Links can be implemented without JavaScript, so long as editors write links as {{DebianBug|NNN}} instead of [[DebianBug:NNN]] or https://bugs.debian.org/NNN. That's more likely to happen if a bot fixes those links automatically.

Boilerplate page headers (e.g. translations) need to be added to the top of each page. Having a bot do that is probably easier than educating each new editor that comes along.

Editorial tasks involve scheduling some action for a particular future date (e.g. deleting a page if nobody objects for one month). Automating those actions would give everyone more certainty about the issue, and might mean non-admin users don't need permission to delete pages themselves.

An alternative would be to encourage people to help clean up the wiki in general, rather than just focus on their little corner of it. This hasn't worked before, because doing so is less inherently rewarding, risks treading on others' toes, and is unnecessarily hard work in MoinMoin.

This hasn't had its own dedicated discussion, and no decision has been made.

Interwiki links vs templates

The current wiki's InterWikiMap is quite large, and Debian Bug Links shows there's interest in pushing beyond what it's designed to handle. MediaWiki interwiki links can only be changed by editing a database table, so a direct translation would be harder to use than the current solution.

Templates are more flexible than interwiki links, and more familiar to users. So far, nobody has objected to the idea of converting interwiki links to templates.

DebianWikiWikiRevamp