From 6dad00ff4c8dd11fec29c3e9ddc7d4f976de60d2 Mon Sep 17 00:00:00 2001
From: Timo Tijhof <krinklemail@gmail.com>
Date: Thu, 27 Sep 2018 21:34:39 +0100
Subject: [PATCH] Document some understanding of MessageCache in
 RawAction/EditPage

Bug: T193271
Change-Id: I8d110dd7b84faf6b1b64553e8088185de5aac7f2
---
 includes/EditPage.php          |  2 +-
 includes/Title.php             | 34 +++++++++++++++++++++++++++++++++-
 includes/actions/RawAction.php | 29 +++++++++++++++++++++++------
 3 files changed, 57 insertions(+), 8 deletions(-)

diff --git a/includes/EditPage.php b/includes/EditPage.php
index 7384ca216c..8c4b3c8257 100644
--- 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 59164e07e7..5b0c3bc2dd 100644
--- 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 817c9fd126..463019f517 100644
--- 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 = '';
 			}
-- 
2.20.1