wiki.techinc.nl/RELEASE-NOTES-1.37

= MediaWiki 1.37 =

== MediaWiki 1.37.0-PRERELEASE ==

THIS IS NOT A RELEASE YET

MediaWiki 1.37 is an alpha-quality development branch, and is not recommended
for use in production.

== Upgrading notes for 1.37 ==
Don't forget to always back up your database before upgrading!

See the file UPGRADE for more detailed per-version upgrade instructions from the
oldest supported upgrading version, MediaWiki 1.27.

Some specific notes for MediaWiki 1.37 upgrades are below:
* …

For notes on 1.36.x and older releases, see HISTORY.

=== Configuration changes for system administrators in 1.37 ===
* …

==== New configuration ====
* …

==== Changed configuration ====
* $wgContentHandlerTextFallback - This setting, which defines how to
  react if a plain text version of a non-text Content object is
  requested using ContentHandler::getContentText(), is deprecated.
* …

==== Removed configuration ====
* $wgLegacyJavaScriptGlobals was deprecated in 1.36.

=== New user-facing features in 1.37 ===
* (T161934) MediaWiki now supports JPEG2000 files, to a limited extent.
* Media files uploaded server side using the importImages.php maintenance
  script now have the "mw-server-side-upload" change tag.
* …

=== New developer features in 1.37 ===
* …

=== External library changes in 1.37 ===
* …

==== New external libraries ====
* Added whatwg-fetch 3.6.2.
* …

===== New development-only external libraries =====
* …

==== Changed external libraries ====
* Updated OOjs from v5.0.0 to v6.0.0
* Updated WVUI from v0.1.0 to v0.2.0
* Updated psr/container from v1.0.0 to v1.1.1.
* Updated wikimedia/minify from v2.2.2 to v2.2.3.
* Updated wikimedia/object-factory from v3.0.0 to v3.0.2.
* Updated wikimedia/parsoid from v0.13.0-a20 to v0.14.0-a1.
* …

===== Changed development-only external libraries =====
* …

==== Removed external libraries ====
* …

=== Bug fixes in 1.37 ===
* …

=== Action API changes in 1.37 ===
* …

=== Action API internal changes in 1.37 ===
* …

=== Languages updated in 1.37 ===
MediaWiki supports over 350 languages. Many localisations are updated regularly.
Below only new and removed languages are listed, as well as changes to languages
because of Phabricator reports.

* (T280435) LRM and RLM characters were removed from names of languages with
  parentheses in Names.php
* (T283422) Add namespace name translations and change the autonym of
  the Kinyarwanda language to "Ikinyarwanda".
* (T283423) Change the autonym of the Lombard language from "lumbaart"
  to "lombard".
* (T279619) Added language support for Dagbani (dag).
* (T282085) Added language support for Malay in Arabic (Jawi) script (ms-arab).
* (T283053) Added language support for Ojibwe (ojb).
* (T283480) Added language support for Wallisian (wls, Fakaʻuvea).
* (T284002) Added language support for Paiwan (pwn).
* (T284044) Added language support for Carpathian Romani (rmc).

=== Breaking changes in 1.37 ===
* The Revision class, hard deprecated in 1.35, is being removed. As
  part of this, the following hooks that included a Revision object
  were removed:
  - ArticleRevisionUndeleted - use RevisionUndeleted
  - ArticleRollbackComplete - use RollbackComplete
  - DiffRevisionTools - use DiffTools
  - DiffViewHeader - use DifferenceEngineViewHeader
  - HistoryRevisionTools - use HistoryTools
  - NewRevisionFromEditComplete - use RevisionFromEditComplete
  - PageContentInsertComplete - use PageSaveComplete
  - PageContentSaveComplete - use PageSaveComplete
  - ParserFetchTemplate - use BeforeParserFetchTemplateRevisionRecord
  - RevisionInsertComplete - use RevisionRecordInserted
  - TitleMoveComplete - use PageMoveComplete
  - TitleMoveCompleting - use PageMoveCompleting
  - UndeleteShowRevision - no replacement
  - UserRetrieveNewTalks - no replacement
  and the following methods and variables have been removed
  - Article::$mRevision
  - Article::getRevisionFetched()
  - ContribsPager::tryToCreateValidRevision()
  - EditPage::$mBaseRevision
  - EditPage::getBaseRevision()
  - LinksUpdate::getRevision()
  - LinksUpdate::setRevision()
  - PageArchive::getArchivedRevision()
  - PageArchive::getPreviousRevision
  - PageArchive::getRevision()
  - Title::countAuthorsBetween()
  - Title::getFirstRevision()
  - User::getNewMessageLinks()
  - User::getNewMessageRevisionId()
  - User::setNewtalk()
  - WikiPage::getOldestRevision()
  - WikiPage::getRevision()
  - WikiPage::getUndoContent()
  - WikiPage::updateIfNewerOn()
  and the following methods no longer accept Revision objects as parameters:
  - CategoryMembershipChange::__construct
  - ContentHandler::getUndoContent
  - DerivedPageDataUpdater::prepareUpdate
  - DifferenceEngine::getRevisionHeader
  - Linker::buildRollbackLink
  - Linker::generateRollback
  - Linker::getRevDeleteLink
  - Linker::getRollbackEditCount
  - Linker::revComment
  - Linker::revUserLink
  - Linker::revUserTools
  - WikiPage::doDeleteUpdates
  - WikiPage::doEditUpdates
  - WikiPage::hasDifferencesOutsideMainSlot
  - WikiPage::onArticleEdit
  - WikiPage::prepareContentForEdit
  - WikiPage::updateRevisionOn
  The following methods return arrays that formerly included a 'revision'
  key that would emit deprecation warnings when accessed and return a
  Revision object. The Revision object has been removed from the arrays,
  and the 'revision-record' key should be used to get the relevant
  RevisionRecord instead:
  - PageUpdater::doCreate
  - PageUpdater::doModify
  - Parser::statelessFetchTemplate
  The ParserOptions `templateCallback` option is a callback that is called
  in Parser::fetchTemplateAndTitle() and should return an array - the
  'revision' key to that array used to be a Revision object and was used if
  no 'revision-record' was returned - it is now ignored.
* WANObjectCache::HOLDOFF_NONE, deprecated since 1.35, was removed.
  Use HOLDOFF_TTL_NONE instead.
* The following methods and fields in the Language class, deprecated since
  1.35, have been removed:
   - classFromCode()
   - clearCaches()
   - convertTitle()
   - findVariantLink()
   - mConverter
   - updateConversionTable()
* The following methods in the Parser class have been removed after having
  been deprecated in 1.35:
   - fetchCurrentRevisionOfTitle()
   - statelessFetchRevision()
   - fetchTemplate()
   - Title()
* (T273354) When an edit is prevented by an 'EditFilterMergedContent' hook
  handler without changing the status, the edit form will now be displayed.
* User::clearNotification() which had been deprecated in 1.35 has been removed.
  Use WatchlistManager::clearTitleUserNotification() instead.
* User::getNewtalk() which had been deprecated in 1.35 has been removed. Use
  TalkPageNotificationManager::userHasNewMessages() instead.
* Autopromote class, deprecated since 1.35, was removed. Use
  UserGroupManager instead.
* The following classes, hard-deprecated since 1.36, have been removed:
  CachedAction, SpecialCachedPage, CacheHelper, ICacheHelper.
* The hooks BeforeHttpsRedirect, CanIPUseHTTPS and UserRequiresHTTPS, deprecated
  in 1.35, were removed.
* The TitleArrayFromResult hook, deprecated in 1.36, was removed.
* The deprecated "es6-promise" alias ResourceLoader module has been removed. Use
  "es6-polyfills" directly intead.
* AuthenticationProvider interface doesn't extend LoggerAwareInterface.
  So AuthenticationProvider can't be typehinted as LoggerAwareInterface.
* The following methods, deprecated in 1.35, were removed:
  - Parser::fetchCurrentRevisionOfTitle
  - Parser::statelessFetchRevision
  - Parser::getRevisionObject
  - ParserOptions::getCurrentRevisionCallback
  - ParserOptions::setCurrentRevisionCallback
* User::getGrantName(), hard deprecated since 1.36, has been removed.
  Use MWGrants::grantName instead.
* SessionProvider class doesn't extend LoggerAwareInterface.
  So SessionProvider can't be typehinted as LoggerAwareInterface.
* The following ApiBase methods, deprecated since 1.35, have been removed:
  - ApiBase::explodeMultiValue
  - ApiBase::parseMultiValue
  - ApiBase::validateLimit
  - ApiBase::validateTimestamp
* User::idCacheByName public static field was removed without deprecation.
  instead of using it, get a UserIdentity by name from UserIdentityLookup.
* IDatabase::upsert() and IDatabase::replace() only accept a single unique key.
  Previously, a warning was issued if there were multiple unique keys provided.
* The MediaWiki:Autoblock_whitelist block exemption control was moved in 1.36 to
  MediaWiki:Block-autoblock-exemptionlist. The backward-compatibility of reading
  the old MediaWiki:Autoblock_whitelist page has now been dropped.
* The following overridable methods in File hierarchy has changed signatures:
  - File::deleteFile - now accepts UserIdentity instead of User
  - File::getDescription - now accepts Authority instead of User
  - File::userCan - now accepts Authority instead of User
  - LocalFile::deleteOldFile - now accepts UserIdentity instead of User
* The following global methods, each deprecated since 1.36, have been removed:
  - wfAppendToArrayIfNotDefault
  - wfAcceptToPrefs
  - wfConfiguredReadOnlyReason
  - wfDebugMem
  - wfGetPrecompiledData
  - wfNegotiateType
* The following deprecated methods of Title class have been removed:
  - nameOf, deprecated in 1.36
  - getPreviousRevisionID, deprecated in 1.34
  - getNextRevisionID, deprecated in 1.34
  - getEarliestRevTime, deprecated in 1.35
* UploadBase::stashFile, deprecated since 1.28, was removed.
* wfGetRusage(), deprecated since 1.35, has been removed.
* The following CLI options were removed from tests/phpunit.php:
  - use-filebackend
  - use-jobqueue
  - use-bagostuff
  The following options (inherited from Maintenance) were also removed:
  - conf
  - dbuser
  - dbpass
  - dbdefaultgroup
  - globals
  - memory-limit
  - profiler
  - server
  The following options were changed to environment variables:
  - wiki => PHPUNIT_WIKI
  - use-normal-tables => PHPUNIT_USE_NORMAL_TABLES
  - use-filebackend => PHPUNIT_USE_FILEBACKEND
  - use-bagostuff => PHPUNIT_USE_BAGOSTUFF
  - use-jobqueue => PHPUNIT_USE_JOBQUEUE
  This is so that we can use the default PHPUnit entry point (T90875).
* The PHPUNIT_REUSE_DB / --reuse-db option was removed from the phpunit.php
  runner. It had been broken for at least three years already. The original use
  case was speeding up tests on Oracle, but Oracle support was dropped several
  releases ago.
* DatabaseBlock::chooseBlock, deprecated since 1.35, was removed.
* SpecialPageFactory::getRestrictedPages, deprecated since 1.36, was removed.
* SpecialBlock::validateTarget, deprecated since 1.36, was removed.
* The PatchFileLocation trait was removed without deprecation.
* ActorMigrationBase::getExistingActorId and ::getNewActorId, hard deprecated
  since 1.36, were removed.
* The protected property LocalFile::$metadata was removed without deprecation.
* …

=== Deprecations in 1.37 ===
* JobQueue::getWiki, deprecated in 1.33, now emits deprecation warnings.
* In AbstractBlock, the getTargetAndType() and getTarget() methods are
  deprecated. Instead use getTargetName() and getTargetUserIdentity() together
  with getType().
* Deprecated passing UserIdentity to
  WatchlistManager::clearAllUserNotifications() and
  WatchlistManager::clearTitleUserNotifications(). Pass Authority instead.
* Deprecated passing LinkTarget to
  WatchlistManager::clearTitleUserNotifications() and
  WatchlistManager::getTitleNotificationTimestamp(). Pass PageIdentity instead.
* Deprecated User::isWatched(), User::isTempWatched(), User::addWatch(), and
  User::removeWatch(). Use corresponding methods in WatchlistManager instead.
* Deprecated WatchAction::doWatchOrUnwatch(). Use WatchlistManager::setWatch()
  instead.
* Deprecated WatchAction::doWatch() and WatchAction::doUnwatch(). Use
  WatchlistManager::addWatch() or WatchlistManager::removeWatch(), instead.
* The getTitle() and setTitle() methods in Parser have been deprecated.
  Use getPage() and setPage() instead.
* Title::isWatchable() has been deprecated. Use WatchlistManager::isWatchable()
  instead.
* wfIncrStats(), deprecated in 1.36, now emits deprecation warnings.
* wfCanIPUseHTTPS() is now deprecated, and always returns true.
* The UserLoadFromDatabase hook has been deprecated. It had no known uses.
* AbstractAuthenticationProvider ::setLogger(), ::setManager(), ::setConfig(),
  ::setHookContainer() were soft deprecated. Use ::init() to inject
  dependencies or override ::postInitSetup() to do any custom
  post-initialization configuration.
* The following methods in ApiPageSet have been deprecated:
   - getTitles(), use getTargets() instead.
   - getGoodTitles(), use getGoodPages() instead.
   - getMissingTitles(), use getMissingPages() instead.
   - getGoodAndMissingTitles(), use getGoodAndMissingPages() instead.
   - getRedirectTitles(), use getRedirectTargets() instead.
   - getSpecialTitles(), use getSpecialPages() instead.
* The following functions from the User class, deprecated in 1.35, now emit
  deprecation warnings:
   - getOptions
   - isIP
   - isUsableName
   - isCreatableName
   - getCanonicalName
* The following methods in User were deprecated:
  - ::idFromName - use UserIdentityLookup::getUserIdentityByName instead.
  - ::resetIdByNameCache - in tests, reset service container. No replacement
    needed in production code.
* Use of ActorMigration for any table except revision, deprecated in 1.34, now
  emits deprecation warnings. Instead of getInsertValues(), use
  ActorNormalization::acquireActorId(). Instead of getWhere() and getJoin(),
  do your own join on the actor table.
* DatabasePostgres::remappedTableName() and its dependent constructor parameter
  'keywordTableMap' are deprecated. Reserved identifiers that are used as table
  names should be quoted where necessary.
* LinkCache::singleton(), deprecated since 1.28, now emits deprecation warnings.
* MessageCache::singleton(), deprecated since 1.34, now emits deprecation
  warnings.
* LockManagerGroup::singleton() and ::destroySingletons(), deprecated since
  1.34, now emit deprecation warnings.
* HtmlFileCacheUpdate::newFromTitles() is now deprecated and emitting warnings.
  Use newFromPages() instead.
* SessionProvider ::setLogger(), ::setManager(), ::setConfig(),
  ::setHookContainer() were soft deprecated. Use ::init() to inject
  dependencies or override ::postInitSetup() to do any custom
  post-initialization configuration.
* User->isLoggedIn(), deprecated since 1.36, now emits deprecation warnings. Use
  the method it wraps, User->isRegistered(), instead.
* FileBackendGroup::singleton() and ::destroySingletons(), deprecated since
  1.35, now emit deprecation warnings.
* JobQueueGroup::singleton was deprecated - use
  MediaWikiServices::getJobQueueGroup instead.
* JobQueueGroup::destroySingletons was deprecated. JobQueueGroups are now
  automatically destroyed after tests.
* SessionProvider ::setLogger(), ::setManager(), ::setConfig(),
  ::setHookContainer() were hard deprecated. Use ::init() to inject
  dependencies or override ::postInitSetup() to do any custom
  post-initialization configuration.
* ContentHandler::getContentText() is now soft deprecated.
  Use Content::getText() instead.
* MediaWiki\User\UserNamePrefixSearch::search() previously accepted as
  its first parameter either the string 'public' or a UserIdentity object,
  to filter results for. It now expects an Authority object instead of
  UserIdentity, and providing just a UserIdentity is hard deprecated.
* wfLocalFile(), deprecated since 1.34, now emits deprecation warnings.
* wfFindFile(), deprecated since 1.34, now emits deprecation warnings.
* User::getRights(), deprecated since 1.34, now emits deprecation warnings.
* User::changeableGroups and ::changeableByGroup were hard deprecated, use
  corresponding methods in UserGroupManager instead.
* User::incEditCount() was deprecated in favor of the new method
  UserEditTracker::incrementUserEditCount().
* RepoGroup::singleton(), ::destroySingleton() and ::setSingleton(),
  deprecated since 1.34, now emit deprecation warnings.
* AbstractAuthenticationProvider ::setLogger(), ::setManager(), ::setConfig(),
  ::setHookContainer() were hard deprecated. Use ::init() to inject
  dependencies or override ::postInitSetup() to do any custom
  post-initialization configuration.
* RecentChange::getPerformer(), hard-deprecated since 1.37,
  use getPerformerIdentity() instead.
* ContentHandler::cleanupHandlersCache(), deprecated since 1.35, now emits
  deprecation warnings.
* File::getUser method was hard deprecated, along with overrides in LocalFile
  and ForeignApiFile in favor of ::getUploader.
* SpecialBlock::checkUnblockSelf(), deprecated in 1.36, now emits deprecation
  warnings.
* (T284179) The mediawiki.viewport ResourceLoader module is deprecated. You can
  now just use MutationObserver or InterSectionObserver directly, which are
  widely available in all supported JavaScript browsers.
* The following constructor options of DatabaseBlock class,
  hard deprecated since 1.37:
  - 'byText' property with blocker's name,
    use 'by' property with UserIdentity value instead.
  - 'by' property with blocker's ID,
    use 'by' property with UserIdentity value instead.
* The BeforeResetNotificationTimestamp hook was deprecated.
* ArchivedFile::getUser, ::getRawUser, ::getRawUserText were deprecated in
  favor of ::getUploader. ::getRawDescription was deprecated in favor of
  ::getDescription with RAW audience parameter.
* When calling LocalFile::newFromRow() or LocalFile::loadFromRow(), passing
  extra fields not requested by ::getQueryInfo() is hard deprecated. This is
  to warn callers that deprefixing and automatic assignment of such fields will
  not be done in a future version.
* JobSpecification::getTitle was deprecated without providing a replacement.
  It wasn't used and job given the purpose of JobSpecification class it's
  not needed.
* The protected method File::getImageSize() is deprecated.
* MediaHandler::getImageSize(), ::getMetadata() and ::isMetadataValid were
  deprecated and should no longer be overridden. Instead, subclasses should
  override getSizeAndMetadata().
* Deprecated File::getMetadata(). Instead use ::getMetadataArray(),
  ::getMetadataItem() and ::getMetadataItems().
* Message::title was deprecated, use Message::page instead.
* …

=== Other changes in 1.37 ===
* WatchlistManager::addWatch and WatchlistManager::addWatchIgnoringRights(),
  which replace User::addWatch(), now call the WatchArticle and
  WatchArticleComplete hooks.
* WatchlistManager::removeWatch and
  WatchlistManager::removeWatchIgnoringRights(), which replace
  User::removeWatch(), now call the UnwatchArticle and UnwatchArticleComplete
  hooks.
* The overridable postInitSetup() method was added to the
  AbstractAuthenticationProvider class. A provider can override postInitSetup()
  to do any custom post-initialization configuration.
* The overridable postInitSetup() method was added to the SessionProvider
  class. A provider can override postInitSetup() to do any custom
  post-initialization configuration.
* The protected getConfig() method was added to the SessionProvider class.
  Use SessionProvider::getConfig to get a config.
* The DBAccessBase class is deprecated. Classes that used to extend it
  should get a load balancer (factory) injected in the constructor instead.
* ActorNormalization::acquireActorId now requires IDatabase parameter.
  Not providing one emitted deprecation warnings since 1.36.
* Anti-lock constants ALF_PRELOAD_LINK, ALF_NO_BLOCK_LOCK, ALF_NO_LINK_LOCK
  and ALF_PRELOAD_EXISTENCE have been removed. They're unused since 1.25.
* …

== Compatibility ==

MediaWiki 1.37 requires PHP 7.3.19 or later and the following PHP extensions:

* ctype
* dom
* fileinfo
* iconv
* intl
* json
* mbstring
* xml

MySQL/MariaDB is the recommended DBMS. PostgreSQL or SQLite can also be used,
but support for them is somewhat less mature.

The supported versions are:

* MySQL 5.5.8 or later
* PostgreSQL 9.4 or later
* SQLite 3.8.0 or later

== Online documentation ==
Documentation for both end-users and site administrators is available on
MediaWiki.org, and is covered under the GNU Free Documentation License (except
for pages that explicitly state that their contents are in the public domain):

       https://www.mediawiki.org/wiki/Special:MyLanguage/Documentation

== Mailing list ==
A mailing list is available for MediaWiki user support and discussion:

       https://lists.wikimedia.org/mailman/listinfo/mediawiki-l

A low-traffic announcements-only list is also available:

       https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce

It's highly recommended that you sign up for one of these lists if you're
going to run a public MediaWiki, so you can be notified of security fixes.

== IRC help ==
There's usually someone online in #mediawiki on irc.libera.chat.