HistoryBlob serialization stability

* Add comments about serialization stability to the HistoryBlob classes
* Clarify the SqlBlobStore comment about legacy encoding

Change-Id: I7dd0f889419ffb5e5dc435e95e02ef05154cd224

4 files changed, 13 insertions, 1 deletions

diff --git a/includes/Storage/SqlBlobStore.php b/includes/Storage/SqlBlobStore.php
index 76c73985f590..7949039a9e5a 100644
--- a/includes/Storage/SqlBlobStore.php
+++ b/includes/Storage/SqlBlobStore.php
@@ -591,7 +591,7 @@ class SqlBlobStore implements IDBAccessObject, BlobStore {
 			$blob = $obj->getText();
 		}
 
-		// Needed to support old revisions left over from the 1.4 / 1.5 migration.
+		// Needed to support old revisions from before MW 1.5.
 		if ( $blob !== false && $this->legacyEncoding
 			&& !in_array( 'utf-8', $blobFlags ) && !in_array( 'utf8', $blobFlags )
 		) {
diff --git a/includes/historyblob/ConcatenatedGzipHistoryBlob.php b/includes/historyblob/ConcatenatedGzipHistoryBlob.php
index af7953290d38..b227c1e7cf5d 100644
--- a/includes/historyblob/ConcatenatedGzipHistoryBlob.php
+++ b/includes/historyblob/ConcatenatedGzipHistoryBlob.php
@@ -23,6 +23,9 @@
 /**
  * Concatenated gzip (CGZ) storage
  * Improves compression ratio by concatenating like objects before gzipping
+ *
+ * WARNING: Objects of this class are serialized and permanently stored in the DB.
+ * Do not change the name or visibility of any property!
  */
 class ConcatenatedGzipHistoryBlob implements HistoryBlob {
 	/** @var int */
diff --git a/includes/historyblob/DiffHistoryBlob.php b/includes/historyblob/DiffHistoryBlob.php
index feddbf6a41cf..8c935163b469 100644
--- a/includes/historyblob/DiffHistoryBlob.php
+++ b/includes/historyblob/DiffHistoryBlob.php
@@ -23,6 +23,9 @@
 /**
  * Diff-based history compression
  * Requires xdiff and zlib
+ *
+ * WARNING: Objects of this class are serialized and permanently stored in the DB.
+ * Do not change the name or visibility of any property!
  */
 class DiffHistoryBlob implements HistoryBlob {
 	/** @var string[] Uncompressed item cache */
diff --git a/includes/historyblob/HistoryBlobStub.php b/includes/historyblob/HistoryBlobStub.php
index 1a70d6bbe12e..d05cd822b96e 100644
--- a/includes/historyblob/HistoryBlobStub.php
+++ b/includes/historyblob/HistoryBlobStub.php
@@ -24,6 +24,12 @@ use MediaWiki\MediaWikiServices;
 
 /**
  * Pointer object for an item within a CGZ blob stored in the text table.
+ *
+ * WARNING: Objects of this class are serialized and permanently stored in the DB.
+ * Do not change the name or visibility of any property!
+ *
+ * Note: the property visibility was changed in 2020 from public to protected.
+ * This may cause problems in future.
  */
 class HistoryBlobStub {
 	/**