Add a usage note to 'CanonicalNamespaces' hook docs

It seems natural to defer namespace configuration until the namespace is
actually registered, but in the case of namespaces that are registered in
CanonicalNamespaces hook, doing so will not work or cause unpredictable
results. This patch adds a note of warning to hooks.txt. See bug 45031 for
context.

Change-Id: I3f2d56dc7ded5e00974de0baf1a84188eade823c

diff --git a/docs/hooks.txt b/docs/hooks.txt
index 0137f5b..ab38936 100644 (file)
--- a/docs/hooks.txt
+++ b/docs/hooks.txt
@@ -760,6 +760,14 @@ $output: OutputPage object in use
 
 'CanonicalNamespaces': For extensions adding their own namespaces or altering
 the defaults.
+Note that if you need to specify namespace protection or content model for
+a namespace that is added in a CanonicalNamespaces hook handler, you
+should do so by altering $wgNamespaceProtection and
+$wgNamespaceContentModels outside the handler, in top-level scope. The
+point at which the CanonicalNamespaces hook fires is too late for altering
+these variables. This applies even if the namespace addition is
+conditional; it is permissible to declare a content model and protection
+for a namespace and then decline to actually register it.
 &$namespaces: Array of namespace numbers with corresponding canonical names
 
 'CategoryAfterPageAdded': After a page is added to a category.