Category talk:Meta/MaintenanceCategory/doc

List of Custom Maintenance Categories

This is similar to the list under #Subcategories, but located here for maintainer convenience. It does not contain the built-in maintenance categories and also lists this page (because there was no way to exclude it).

Overview

This is a hidden meta category for custom wiki maintenance categories that show pages containing an issue in need of maintenance. In this context Meta primarily means "categories about the wiki" rather than "categories about categories", though this one is both!

Purpose

They are intended to be modeled after and used for the same purpose as built-in special pages reports and tracking categories like:

Though they are different in a couple significant ways which are covered in detail in the next section.

Differences from Built-Ins

Never Empty

In order to facilitate identifying the templates where a custom maintenance category is used, those templates should always be a member of the category, so at a minimum each category should contain at least one template as a member.

See #Finding Uses of a Maintenance Category for more details on how this should be implemented.

Always Exist

A custom maintenance category will always exist by default[*], even if there are no pages with the described issue in it. There are a few reasons for this:

To document the purpose of it
To help identify templates which use it (see #Finding Uses of a Maintenance Category)
To include it in this parent category for easy browsing by maintainers

[*]: Category:Pages using duplicate arguments in template calls did not exist by default despite the fact that MediaWiki will conditionally add pages to that category automatically, but it was created to add it to this category, along with the others from Special:TrackingCategories. As new versions of MediaWiki and Extensions are added and new tracking categories show up those will be created and added to this category as well.

Visibility

The built-in maintenance categories are effectively error messages and are not hidden from the user by default. Ideally custom maintenance categories should be this way as well, but often the need for them is realized only after the problem already exists in many places so custom maintenance categories are often hidden by default, at least initially.

See #Hiding for more details on how this should be implemented.

Creating a Maintenance Category

For each maintenance category there are two components, the maintenance category itself, and the template(s) which contain logic to conditionally add that category to a page.

Maintenance Category

Name

All maintenance category names should begin with Category:Meta/ to differentiate them and ensure they are included in the list at the top of this page.

Hiding

Generally these maintenance categories are more like Category:Pages using duplicate arguments in template calls than the special pages reports in that they are intended to be shown to the user by adding a category to the page so that recent edits which introduce one of these issues can be spotted and corrected immediately.

However, in cases where one of these is added retroactively to an existing template which is transcluded in a large number of pages it may be desirable to initially create it as a Hidden Category until initial maintenance can be performed to fix preexisting instances of the problem before it starts showing up to everyone.

That can be accomplished by temporarily adding this to the new maintenance category:

<!-- temporarily hidden until preexisting instances of this issue can be resolved,
     remove once the only members of this category are the templates which use it -->
__HIDDENCAT__

A hidden maintenance category will still be visible from this parent category, but if you're maintaining the wiki you may want to enable showing hidden categories in your preferences so that it will also show on pages which have that issue:

 Preferences => Appearance => Show hidden categories.

Empty Template

This is a [hidden] maintenance category to help identify all the pages where [description], e.g.:
<pre>
{{SomeTemplate
|SomeExample = of an incorrect usage of this template which will put a page in this category
}}
</pre>

<!-- temporarily hidden until preexisting instances of this issue can be resolved,
     remove once the only members of this category are the templates which use it -->
__HIDDENCAT__

[[Category:MaintenanceCategory]]

Conditionally Add Maintenance Category in a Template

The template portions of these maintenance categories are generally implemented with parser functions which are themselves special kinds of templates to perform conditional logic. Because of this you may need to pay special attention to parser functions in templates depending on what you're trying to do (it's templates all the way down!). It may also help to familiarize yourself with some of the more exotic template usage options for implementing these.

You can look at the source of any of the templates which include one of the #Subcategories to see real examples. Those can be found by going to the page for any of the Subcategories and looking for templates which are a member (see #Finding Uses of a Maintenance Category).

However, the most basic form of a maintenance category is one which simply checks whether a template parameter contains or does not contain some string.

Template parameter contains string

<!-- this is the conditional include block, note the use of <includeonly> -->
{{#ifexpr:{{#invoke:String|find|source={{{foo}}}|target=bar}}|<includeonly>[[Category:Meta/Page where the foo template parameter contains bar]]</includeonly>|<!-- no case, the page is good! (this section and the preceding pipe can be omitted in this case) -->}}

<noinclude>[[Category:Utility Template]]</noinclude>
<!-- this is the unconditional include block, note the use of <noinclude> -->
<noinclude>[[Category:Meta/Page where the foo template parameter contains bar]]</noinclude>

Template parameter does not contain string

{{#ifexpr:{{#invoke:String|find|source={{{baz}}}|target=qux}}|<!-- yes case, the page is good! -->|<includeonly>[[Category:Meta/Page where the baz template parameter does not contain qux]]</includeonly>}}

<noinclude>[[Category:Utility Template]]</noinclude>
<noinclude>[[Category:Meta/Page where the baz template parameter does not contain qux]]</noinclude>

Finding Uses of a Maintenance Category

One of the pernicious things about conditional categories is that it can be difficult to find all the pages where they are being conditionally included after the fact when those conditions are false.

To solve this problem we follow the convention that all maintenance categories are conditionally included in the templates they are used in within an <includeonly> block AND unconditionally included in those same templates inside a <noinclude> block. In this way every template which uses a maintenance category will be a member of that category (so they can be easily identified) but every page which uses that template will only be a member of the maintenance category when the condition dictates it so. The <includeonly> tags on the conditional instances are redundant in this case, but they're there to further emphasize and differentiate the conditional include case(s) from the unconditional one (at the bottom of the template with the <noinclude>[[Category:Utility Template]]</noinclude> by convention).

As a result every maintenance category will have at a minimum the templates which use them as members (no maintenance category should ever be completely empty, and if is that should indicate it is unused if these conventions were followed).

Empty Template

{{#if:<condition>|<includeonly>[[Category:Meta/Page where <condition where category is included>]]</includeonly>}}

<noinclude>[[Category:Utility Template]]</noinclude>
<noinclude>[[Category:Meta/Page where <condition where category is included>]]</noinclude>

Notes

These category pages don't populate immediately since they are based on templates and MediaWiki processes template updates to existing pages which transclude that template via asynchronous jobs.