WikiRevamp: Difference between revisions

Latest revision as of 09:04, 28 August 2026

Note: This was generated using Pandoc to convert MoinMoin's parsed HTML output directly into MediaWiki syntax. This is an experiment to check fidelity.

At DebConf25, a BOF was dedicated to discuss the state of the Debian Wiki.^[1] Known historical issues were summarized, in particular:

The wiki relies on old software.
There are no clear guidelines on the scope of what is and is not appropriate wiki content.
There is no "default" license, most of the pages don't specify one and the few who do use a variety 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.

In the following days, action was taken about this.

Participating

Want to help? Start by reading the very next section below on channels of communication. On IRC, you can ask how you can help and participate in discussions regarding migration and licensing.

Communication

The debian-wiki mailing list was created to discuss the Wiki, in addition to the #debian-wiki IRC channel. If you want to participate, you are encouraged to reach via at least one, but ideally both of them, as discussions often occur on both at the same time.

Software migration

See also: The MediaWiki next steps thread on the debian-wiki mailing list

During the BOF, the possibility was brought up of a migration to MediaWiki: 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.debian.org, a machine running Debian Trixie that hosts a MediaWiki instance. It can be accessed at wiki2025.debian.org.

Do not begin to migrate content here yet, though, as it could still be erased 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 the edit history of each as well as convert the content to the MediaWiki syntax as a final stage at the end. This is achieved by accessing the internal file-based database for MoinMoin. You can find a demonstration of this at FreedomBox (in particular, the preservation of the edit history), which is the end result of using the migration tools on the old wiki's page about the same software.

Current resources for conversion:

@guillem: A Debian fork of the mm2mw Perl scripts for migrating the old edit histories as well as converting the syntax (evolving at guillem/mm2mw on Salsa).
@maytham: Shell scripts to retain edit histories, but without syntax conversion, developed at Maytha8/wiki-scripts on Salsa.
@sunilmohan: sunilmohan/moinmoin_to_mediawiki on Salsa (based on a tool to generate the FreedomBox manual PDF).
@AndrewSayers: AndrewSayers/mediawiki-recommendations on Salsa (a counterpart to the recommendations page on the old wiki).

The configuration and extensions for the new instance have not been finalized yet. @maytham is working on an extension (Salsa repository) to provide it with the Debian navigation bar 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 already packaged for Debian.

Content licensing

The migration provides a good opportunity to think about the long-standing licensing problems that are often interpreted to mean that content from the old wiki cannot in fact be reused or redistributed legally.

Since 2025-07-24, new content on the MoinMoin-based wiki is released under the terms of the Creative Commons Attribution-ShareAlike License, version 4.0 (CC-BY-SA-4.0),^[2] unless otherwise noted, so non-copyrighted work will gradually be replaced even absent an orchestrated migration effort.

The migration will most likely work like those that occurred for previous MoinMoin version bumps: the old edit history will be retained, followed by a conversion edit to migrate any deprecated syntax. That ensures the migration to MediaWiki isn't blocked on the time-consuming process of rewriting content, and the licensing issues will eventually fade away with the passage of time.

Choice of license

The Creative Commons license was agreed upon between participants on the mailing list and IRC because it:

is designed for and applies to content, in contrast to other licenses that are aimed at software source code;
requires attribution for contributors' hard work;
ensures any adaptations of the work remain available for reuse/redistribution under the same terms, preventing potential future bad actors from taking the work and making it proprietary; and
is relatively permissive and compatible with the GNU GPL v3.0.

Frequently asked questions

See also: The Re: Content licensing thread on the debian-wiki mailing list
Why not a dedication to the public domain, a la CC0?: 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 the public domain except other public domain content.
Why not Expat (a.k.a., the MIT License)?: That license is intended for software, whereas the Creative Commons licenses are intended for use specifically with non-software works. Note that the Debian website proper (www.debian.org) uses this, though.
Why not GFDL?: In 2006, Debian Developers approved a General Resolution that defined the project's official posture towards the GFDL, declaring it DFSG-incompatible except when it is used without any of its invariant options. It is also much more restrictive, thereby reducing the possibility of reusing wiki content elsewhere, such as in man pages or the official documentation.
Why not Creative Commons' NonCommercial (NC) or NoDerivatives (ND) options?: Neither of those are DFSG-compatible.

Old content

@maytham is leading an ongoing relicensing effort (coordinated in the Maytha8/wiki-relicensing repository on Salsa), seeking to make contact with all previous Debian Wiki contributors and obtain permission for their work to be re-licensed under CC-BY-SA-4.0.

New content

Notices have been added to the current wiki stating that any contributions submitted after midnight UTC on 2025-07-24 are released under CC-BY-SA-4.0, unless otherwise noted. A copyright.html page^[2] has also been written up with details on how to be compliant with the license.

Recommendations and mass edits

Before the old wiki can be migrated in bulk, we need to identify all the ways in which it will behave differently and work out how to adapt to 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 use the same page name as their "content space" counterparts but nevertheless exist in parallel and separate namespaces that have the word Talk: appended, e.g., Category_talk:, and are linked from above the page content. Rules and recommended processes are being written up at WikiRevamp/Recommendations on the old wiki.

Several differences involve converting loose editing conventions to automated rules by writing pattern-matching code and doing mass edits to normalize all of the migrated content under a single, workable format. For example, "discussion" links on the old wiki have almost always been added by individual editors with page-specific styling. Every instance of that will need to be removed or massaged into conformity with the migration tool's definition of acceptable syntax. 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 on Salsa.

Specific mass edits

A "mass edit" refers to using an automation tool to process and edit a great many (usually hundreds or thousands) of pages at once with the goal of tackling very pervasive formatting issues in a deterministic manner. The term itself is a reference to MediaWiki's own MassEditRegex extension.

Some target objectives for these tasks have already been identified.

#language tags (2025-08-17): Many old wiki pages have a processing instruction such as #language pt_BR. This edit changed about 15 pages with errors in their processing instructions; see the mailing list thread for more details.
Category footers (2025-08-17): Categories are generally appended to pages after a horizontal rule generated by entering four consecutive hyphen-minuses on a line by themselves in the page's source code. This edit changed about 620 pages containing issues that made it harder to detect the category list; see the mailing list thread for more details.
<<FullSearch>> (2025-09-06 and 2025-09-07): MoinMoin's <<FullSearch>> macro doesn't have a direct MediaWiki equivalent, so we will need to convert it differently depending on its contents. This edit changed about 130 pages in an effort to reduce the number of patterns that need to be considered; see the mailing list thread for more details.
Translation page names (2025-10-04): Translations should have page names that resemble each other, but many old wiki pages don't fit that pattern, such as when some language translations haven't been updated since the English version was renamed). This edit renamed approximately 100 pages to fit the normal naming convention; see the mailing list thread for more details.
Non-wiki #formats (2026-02-20 and 2026-02-21): MoinMoin's #format processing instruction isn't widely used, but adds another special case to the migration process; consider using a page-wide #!highlight block instead. See the mailing list thread for more details.

Responding to mass edits

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 username of the person managing the edit (e.g. Andrew Sayers).

If you wish to object to an upcoming mass edit, contact the mailing list (preferably in a reply to that edit's announcement thread) before it occurs and explain your objection. We'll talk through the issue and look for suitable ways to change the upcoming work. 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," and then write a longer reply a few days later.

If you want to object to an already-completed mass edit, you should again make contact on the mailing list after reverting the change, explaining your objection. We'll 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

Be advised: ⚠️ This section attempts to summarize conversations from the mailing list and IRC channel. It will always be somewhat out-of-date and incomplete. ⚠️

Debian Bug Tracker links

See also: The DebianBug links thread on the mailing list.

The current wiki renders links to Debian and Ubuntu bugs with a distinct style, receiving a title attribute with their subject line, with closed bugs also shown struck with a line through them. For example, the following bugs should be struck through, and you should see a tooltip with their subject line when you hover your mouse pointer over them: Bug #399237 and LP #1597017.

At the code level, this is implemented by including bugstatus.js in every page, where it scans the HTML for those specific link types 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 the eponymous launchpadlib Python module.

The MediaWiki alternatives to these approaches include:

MediaWiki:Common.js is a JavaScript file included in every page on a wiki. This is the alternative that's most similar in function, but it can be hard to manage because of the temptation to put unrelated content in the same file.
The MediaWiki Gadgets extension is a more powerful alternative to MediaWiki:Common.js, and seems like the natural choice for a replacement for the current MoinMoin implementation.
Scary transcluding lets you include pages and templates from other wikis with a cache for the page data and 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 synchronizing the 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 eventually make use of.

Migrating user accounts

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

The plan is to switch from MoinMoin's built-in user database to authenticating using 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 and give account holders from the old wiki replacement accounts on Salsa with the same username, and ask them to change their information if they want.

Boilerplate page headers

Pages often start with some boilerplate text (i.e., translation headers). Putting a common header template on all pages would make it easier to manage that text; see Template:PageHeader for an initial demonstration of how that might look. This has been mentioned in passing, but no firm decision has yet been made.

Translations

See also: The "Info request on new Wiki translations - any automatic handling of translation headers and translated pages?" thread on the mailing list.

We plan to install MediaWiki's Translate extension to handle content localization workflows. The benefits of doing this include:

No need to maintain a TAG:TRANSLATION-HEADER block, instead just add <languages /> to the top of a page and the rest is handled automatically on the backend.
- For a good example of this extension in action, check out the "Languages" block at the top of Translate extension's help page.
It provides advanced translation tools, like always showing up-to-date completion progress for each language and suggesting machine translation suggestions to translators directly within the interface.
It will likely be familiar to people coming here from other MediaWiki-based wikis, too.

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

Another approach would be to write our own custom templates for managing translations (see ExampleForTranslation for a proof of concept). 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.

Still another alternative would be OpenStreetMap Wiki's Languages template, which is powered by 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 found in MediaWiki's solution.

We plan to include a template for linking to localized versions of pages, so for example, if you're translating Some page and encounter a link to This other page, you would only need to use a simple syntax like {{Ll|This other page}} to create a link to that page's translations to the same language on all of the translations of Some page; see MediaWiki's Localized link template, OpenStreetMap Wiki's LL template, and our very own Template:Ll right here to compare the implementation choices.

Editorial tasks (e.g. CategoryProposedDeletion)

See also: The summary of the IRC discussion surrounding "Issues around CategoryProposedDeletion".

On the MoinMoin wiki, pages are added to editorial categories like CategoryProposedDeletion, with the expectation that the editorial work will be undertaken at some time in the future. That editorial process is discussed in the editor guide there.

MediaWiki makes it easy to create more verbose and precise admonitions, with guidance on the page itself; see the pro forma ExampleForProposedDeletion for one potential style.

Scope

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

A draft of potential guidelines was published at MaythamAlsudany/DraftContentGuidelines on the old wiki, with related discussions about them ongoing at the /Discussion subpage.

Milestones and gamification

MediaWiki automatically sends editors congratulatory notifications when they make a "milestone" number of edits (1st, 10th, 100th, etc.). This can be disabled by going to your User preferences page and disabling the "Edit milestone" option, but there doesn't seem to be a way to disable this by default for all new users.

Automated bot edits

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

The Debian Bug Tracker links handling could be implemented without JavaScript, so long as editors remember to create links to them as template calls (a la {{DebianBug|NNN}}) instead of [[DebianBug:NNN]] or [https://bugs.debian.org/NNN Bug #NNN]. That's more likely to happen if a bot fixes those links automatically.
Boilerplate page headers, such as those for 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, but this hasn't had its own dedicated discussion, and no decision has been made.

Interwiki links vs. templates

See also: The brief mention in the "Re: Complex conversion issues" thread on the mailing list, and the resulting DebianIRC template.

The current wiki's InterWikiMap is quite large, and as evidenced by the debate over Debian Bug links there's interest in pushing beyond what it's currently 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 also more familiar to users. So far, nobody has objected to the idea of converting most interwiki links to templates.

References

↑ Etherpad from the BOF.
↑ ^2.0 ^2.1 Copyright page on the old Debian Wiki.