Feature summary (what you would like to be able to do and where):
The AbuseFilter interface currently provides two fields for documenting a filter: a single-line Description field and a plain-text Notes field.
- Please add a new Summary field positioned between the description and the filter conditions, formatted as wikitext, and subject to the same access controls as the filter itself.
- Please allow the search at Special:AbuseFilter to search the summary (in addition to or instead of the conditions).
Use case(s) (list the steps that you performed to discover that problem, and describe the actual underlying problem which you want to solve. Do not describe only a solution):
The existing documentation fields each have significant limitations.
- Description: a short single-line which is only suitable as a short label. More importantly, it is always public so filters that target long-term abuse (LTA) patterns, specific sockpuppets, or other sensitive activity cannot describe their purpose accurately without tipping off bad actors. Editors working with these filters must resort to obfuscating names that convey little information to other filter editors.
- Notes: The notes field is plain text so it isn't possible to link to relevant pages such as related project space pages, sockpuppet investigation cases, RFCs that led to filters being added, user accounts, etc. The notes field also sits below the filter conditions. That's fine for a change log, but this has led to a common anti-pattern: abuse filter managers often put a summary of the filter's purpose, false positive handling guidance, etc. into a C-style comment at the top of the filter conditions themselves. This pollutes the conditions with documentation and makes both harder to read. And the notes field itself tends to grow into a long change-log with a summary at the top that often becomes stale.
- The search function at Special:AbuseFilter is only able to search filter conditions, which is another reason why comments are being added to filters.
- Because there is no dedicated summary field, filter documentation ends up in inconsistent locations. Sometimes, it's a comment at the top of conditions, sometimes it's at the top of the notes field, and sometimes it's even documented separately in an index to work around the lack of search. This makes it impossible for scripts to reliably surface a summary without parsing free-form text.
- Wikitext links such as [[Wikipedia:Sockpuppet investigations/...]] are inert inside these text fields. In a wikitext summary field they would be functional links.
Some examples from English Wikipedia:
- https://en.wikipedia.org/wiki/Special:AbuseFilter/2 (private index to work around search deficiencies)
- https://en.wikipedia.org/wiki/Special:AbuseFilter/614 (public meme filter)
- https://en.wikipedia.org/wiki/Special:AbuseFilter/1361 (private LTA filter)
- https://en.wikipedia.org/wiki/Special:AbuseFilter/1402 (example using notes instead of conditions)
Benefits (why should this be implemented?):
A wikitext summary field, placed above the conditions and governed by the filter's own access level, would:
- Allow private filters to include a frank, detailed description of their purpose including links to relevant pages without exposing sensitive information publicly.
- Give filter editors a natural place for structured documentation (purpose, false positive guidance, maintenance notes) that is cleanly separated from the conditions and from the append-style notes field.
- Eliminate the need to embed general documentation in C-style comments inside the filter conditions, and reduce the pressure on the notes field to serve as both summary and change log.
- Support links to related pages without requiring client-side workarounds (see https://en.wikipedia.org/wiki/User:Suffusion_of_Yellow/filterNotes for an example).
- Allow each wiki to adopt its own documentation conventions using wikitext section headings (e.g. "False positive reports", "Maintenance notes", "Currently targeting"), without requiring any schema changes.
- Allow better integration with Wikipedia tooling: popup scripts could display the lead section of the summary field as a hover summary when browsing a filter link on noticeboards, filter hits in the abuse log, etc.