Hooks do not have to return true any more, they can return null

Via the argument given by Krinkle in
https://gerrit.wikimedia.org/r/#/c/274751/1/ImageMap_body.php

Quote: "[Returning true is] obsolete for a while and slowly disappearing
from existing code. Only 'return false' is an explicit signal. The
default is true. This was done because it very often is forgotten and
causes broke in production in catastrophic ways on numerous occasions.
This better reflects the mental model of intent and also makes it more
natural when dealing with hooks such as these, which can't be aborted
and as such don't have a sensible purpose in returning false, which
means returning true can be confusing."

Change-Id: I98308ed9105d904e47db3ac7899412f239c2bf9d

diff --git a/docs/hooks.txt b/docs/hooks.txt
index c5f2424..a431f1b 100644 (file)
--- a/docs/hooks.txt
+++ b/docs/hooks.txt
@@ -178,7 +178,8 @@ once for 'TimStarling', and once for 'brion'.
 
 Hooks can return three possible values:
 
-  * true: the hook has operated successfully
+  * No return value (or null): the hook has operated successfully. Previously,
+    true was required. This is the default since MediaWiki 1.23.
   * "some string": an error occurred; processing should stop and the error
                    should be shown to the user
   * false: the hook has successfully done the work necessary and the calling