Document some understanding of MessageCache in RawAction/EditPage

Bug: T193271
Change-Id: I8d110dd7b84faf6b1b64553e8088185de5aac7f2

diff --git a/includes/EditPage.php b/includes/EditPage.php
index 7384ca2..8c4b3c8 100644 (file)
--- a/includes/EditPage.php
+++ b/includes/EditPage.php
@@ -2716,7 +2716,7 @@ ERROR;
         *
         * @param string|null|bool $text Text to unserialize
         * @return Content|bool|null The content object created from $text. If $text was false
-        *   or null, false resp. null will be  returned instead.
+        *   or null, then false or null will be returned instead.
         *
         * @throws MWException If unserializing the text results in a Content
         *   object that is not an instance of TextContent and

diff --git a/includes/Title.php b/includes/Title.php
index 59164e0..5b0c3bc 100644 (file)
--- a/includes/Title.php
+++ b/includes/Title.php
@@ -4778,7 +4778,39 @@ class Title implements LinkTarget {
        }
 
        /**
-        * Get the default message text or false if the message doesn't exist
+        * Get the default (plain) message contents for an page that overrides an
+        * interface message key.
+        *
+        * Primary use cases:
+        *
+        * - Article:
+        *    - Show default when viewing the page. The Article::getSubstituteContent
+        *      method displays the default message content, instead of the
+        *      'noarticletext' placeholder message normally used.
+        *
+        * - EditPage:
+        *    - Title of edit page. When creating an interface message override,
+        *      the editor is told they are "Editing the page", instead of
+        *      "Creating the page". (EditPage::setHeaders)
+        *    - Edit notice. The 'translateinterface' edit notice is shown when creating
+        *      or editing a an interface message override. (EditPage::showIntro)
+        *    - Opening the editor. The contents of the localisation message are used
+        *      as contents of the editor when creating a new page in the MediaWiki
+        *      namespace. This simplifies the process for editors when "changing"
+        *      an interface message by creating an override. (EditPage::getContentObject)
+        *    - Showing a diff. The left-hand side of a diff when an editor is
+        *      previewing their changes before saving the creation of a page in the
+        *      MediaWiki namespace. (EditPage::showDiff)
+        *    - Disallowing a save. When attempting to create a a MediaWiki-namespace
+        *      page with the proposed content matching the interface message default,
+        *      the save is rejected, the same way we disallow blank pages from being
+        *      created. (EditPage::internalAttemptSave)
+        *
+        * - ApiEditPage:
+        *    - Default content, when using the 'prepend' or 'append' feature.
+        *
+        * - SkinTemplate:
+        *    - Label the create action as "Edit", if the page can be an override.
         *
         * @return string|bool
         */

diff --git a/includes/actions/RawAction.php b/includes/actions/RawAction.php
index 817c9fd..463019f 100644 (file)
--- a/includes/actions/RawAction.php
+++ b/includes/actions/RawAction.php
@@ -163,13 +163,30 @@ class RawAction extends FormlessAction {
                $title = $this->getTitle();
                $request = $this->getRequest();
 
-               // If it's a MediaWiki message we can just hit the message cache
+               // If it's a page in the MediaWiki namespace, we can just hit the message cache
                if ( $request->getBool( 'usemsgcache' ) && $title->getNamespace() == NS_MEDIAWIKI ) {
-                       // The first "true" is to use the database, the second is to use
-                       // the content langue and the last one is to specify the message
-                       // key already contains the language in it ("/de", etc.).
-                       $text = MessageCache::singleton()->get( $title->getDBkey(), true, true, true );
-                       // If the message doesn't exist, return a blank
+                       // FIXME: The overhead and complexity of using MessageCache for serving
+                       // source code is not worth the marginal gain in performance. This should
+                       // instead use Revision::getRevisionText, which already has its own caching
+                       // layer, which is good enough fine given action=raw only responds with
+                       // a single page (no need for batch).
+                       //
+                       // Use of MessageCache:
+                       // - is unsustainable (T193271),
+                       // - can cause bugs due to "post-processing" (see MessageCache::get) not
+                       //   intending to apply to program source code,
+                       // - causes uncertaintly around whether or not localisation default
+                       //   placeholders are, can, and should be used, or not.
+                       $text = MessageCache::singleton()->get(
+                               $title->getDBkey(),
+                               // Yes, use the database.
+                               true,
+                               // Yes, use the content language.
+                               true,
+                               // Yes, the message key already contains the language in it ("/de", etc.)
+                               true
+                       );
+                       // If the local page doesn't exist, return a blank (not the default)
                        if ( $text === false ) {
                                $text = '';
                        }