Page MenuHomePhabricator

Convert hooks.txt to YAML [Outreachy microtask]
Open, NormalPublic

Description

hooks.txt contains all MediaWiki core hooks in an almost-but-not-quite machine-readable format. Commits that change a hook but don't update hooks.txt are flagged in code review so this file tends to be up to date but not very user-friendly.

Manual:Hooks is a human-readable directory of hooks. It has some navigation aids, translations and significantly more information than hooks.txt but is often outdated and some hooks are outright missing.

The best of both worlds would be to make hooks.txt properly machine-readable, and the data in it available to wiki templates so that they can automatically pull details and stay up-to-date, and a bot can create missing hook pages. YAML is a nice language for that as it is both machine- and human-readable (especially if we avoid its more complex features).

Write and publish a script to convert hooks.txt to hooks.yaml (language is up to you), then submit a patch to MediaWiki core that replaces the file.

The details are up to you but you could e.g. transform this:

'EditPageGetDiffText': DEPRECATED! Use EditPageGetDiffContent instead.
Allow modifying the wikitext that will be used in "Show changes". Note that it
is preferable to implement diff handling for different data types using the
ContentHandler facility.
$editPage: EditPage object
&$newtext: wikitext that will be used as "your version"

to this:

EditPageGetDiffText:
  DEPRECATED: Use EditPageGetDiffContent instead.
  description:
    Allow modifying the wikitext that will be used in "Show changes". Note that it
    is preferable to implement diff handling for different data types using the
    ContentHandler facility.
  arguments: 
    - "$editPage": EditPage object
    - "&$newtext": wikitext that will be used as "your version"

(Before merging we'll have to update maintenance/findHooks.php but that's not part of this task.)


The main task of the Outreachy project is T91626: Technology to transclude git content into wiki pages.

Event Timeline

Tgr created this task.Oct 13 2015, 8:21 PM
Tgr raised the priority of this task from to Normal.
Tgr updated the task description. (Show Details)
Tgr added a project: MediaWiki-Documentation.
Tgr added subscribers: Tgr, Spage, bd808.
Restricted Application added a project: Documentation. · View Herald TranscriptOct 13 2015, 8:21 PM
Restricted Application added a subscriber: Aklapper. · View Herald Transcript
Tgr updated the task description. (Show Details)Oct 13 2015, 8:33 PM
Tgr set Security to None.
Tgr updated the task description. (Show Details)Oct 13 2015, 8:44 PM
Tgr assigned this task to Akangupt.Oct 13 2015, 9:10 PM

I have written a PHP script which coverts a text file in a yaml format. Please find the attached hooks.yaml (

), which I got after running my script. Does this look good?

hooks.txt has a lot of test cases and I tried to cover all of them using regular expressions. I tested hooks.yaml manually and on one online YAML parser. I don't know what exactly would be the best method to test if some information is getting lost/misinterpreted from hooks.txt to hooks.yaml.

YAML syntaxes like literal blocks, sequences and maps might make it inconvenient for developers adding hooks. Should we add some instructions in hooks.yaml for adding hooks?

key: value (Plainer style) has a lot of limitations . Top of that, It has a lot more limitations on first character. All these limitations make it difficult to follow. So, whenever a line contains a character that doesn't belong to A-Z a-z 0-9 _ . \n space , I used '|' .

I preferred '|' over '>' because of test cases in which we would like to preserve new line breaks for example, in argument $param :

'LogEventsListShowLogExtract': Called before the string is added to OutputPage.
Returning false will prevent the string from being added to the OutputPage.
&$s: html string to show for the log extract
$types: String or Array Log types to show
$page: String or Title The page title to show log entries for
$user: String The user who made the log entries
$param: Associative Array with the following additional options:
  - lim Integer Limit of items to show, default is 50
  - conds Array Extra conditions for the query (e.g. "log_action != 'revision'")
  - showIfEmpty boolean Set to false if you don't want any output in case the
    loglist is empty if set to true (default), "No matching items in log" is
    displayed if loglist is empty
  - msgKey Array If you want a nice box with a message, set this to the key of
    the message. First element is the message key, additional optional elements
    are parameters for the key that are processed with
    wfMessage()->params()->parseAsBlock()
  - offset Set to overwrite offset parameter in $wgRequest set to '' to unset
    offset
  - wrap String Wrap the message in html (usually something like
    "<div ...>$1</div>").
  - flags Integer display flags (NO_ACTION_LINK,NO_EXTRA_USER_LINKS)

Here is the script for this task P2218 and corresponding yaml file

.

Change 248677 had a related patch set uploaded (by Akangupt):
Adding hooks.yaml for T115388

https://gerrit.wikimedia.org/r/248677

Change 248677 had a related patch set uploaded (by Akangupt):
Convert hooks.txt to hooks.yaml

https://gerrit.wikimedia.org/r/248677

hashar added a subscriber: hashar.Oct 28 2015, 8:46 PM

Hello @Akangupt. At first: I am a huge fan of YAML which is very convenient for human consumption and has a ton of nice features.

The hooks documentation definitely needs love. I did an attempt ages ago to convert the plain text file to doxygen format which we use to generate the mediawiki/core doc. Got buried / abandoned eventually https://gerrit.wikimedia.org/r/#/c/66128/ . So I am quite happy to see this task!

A potential concern (from T116965) is: that the YAML file defines a layout. We would want to make sure that future changes will not break it and respect whatever fields are required. Maybe that is out of the scope of this task though.

Do we have any idea what is going to consume the .yaml file?

Tgr added a comment.Oct 28 2015, 11:07 PM

Yes, this is an Outreachy microtask so the scope needs to be limited. Those issues need to be solved before the patch can be merged, but are not part of this task.