Extension:BetaFeatures/How to setup a beta feature

This document (written in June 2026) documents how to create a beta feature in Wikipedia production.

Why?

Running a beta feature de-risks your large deployment by allowing editors to try out your feature prior to launch. Even for reader features this can be useful, as rolling back for anonymous users can often be disruptive and problematic (due to the fact we cache for logged in users). If users have concerns about your feature, it is better to hear from them during the beta feature then 1 week after everyone has the feature.

Note: many editors automatically opt into new beta features by default so they can keep tabs on new developments.

Process

[edit ]

Preparation work [design and PM]

[edit ]

Create a screenshot. Review https://www.mediawiki.org/wiki/Special:Preferences#mw-prefsection-betafeatures for the style and consider if you need RTL and LTR variants.
Identify a mediawiki page and corresponding talk page to direct editors to where they can learn about the feature
Identify copy text for beta feature (see preferences page for example). In your description it is recommended that you establish expectations to editors under the circumstances the feature should leave beta

Setting up the beta feature [developers]

[edit ]

Enable beta features using the GetBetaFeaturePreferences hook . You’ll need to provide a screenshot screenshot link info-link t, a discussion link discussion-link and two messages - a label label-message and description description-message
I recommend enabling the beta feature with a static configuration flag so you can control the roll out.
Consider limiting the beta feature to certain skins.

Example:

<?php
namespace MediaWiki\Extension\ReadingLists;
use MediaWiki\Config\Config;
use MediaWiki\Context\RequestContext;
use MediaWiki\Extension\BetaFeatures\Hooks\GetBetaFeaturePreferencesHook;
use MediaWiki\MainConfigNames;
use MediaWiki\User\User;
/**
* This handler is separated from the main HookHandler to allow use of type
* validation via the hook interface, without a hard dependency on BetaFeatures.
* It is important that this class only be referenced/loaded by code
* controlled by the BetaFeatures extension, to keep it a soft dependency.
*/
class BetaFeatureHookHandler implements GetBetaFeaturePreferencesHook {
  public function __construct(
      private readonly Config $config,
  ) {
  }
  /**
   * @see https://www.mediawiki.org/wiki/Manual:Hooks/GetBetaFeaturePreferences
   *
   * @param User $user
   * @param array[] &$prefs
   */
  public function onGetBetaFeaturePreferences( User $user, array &$prefs ) {
      if ( !HookHandler::isSkinSupported( RequestContext::getMain()->getSkinName() ) ) {
          return;
      }
      if ( $this->config->get( 'MyExtensionNameBetaFeature' ) ) {
          $path = $this->config->get( MainConfigNames::ExtensionAssetsPath );
          $prefs['myextension-beta'] = [
              'label-message' => 'myextension-beta-feature-name',
              'desc-message' => 'myextension-beta-feature-description',
              'screenshot' => "$path/MyExtension/resources/assets/beta-feature.svg",
              'info-link'
                  => 'https://www.mediawiki.org/wiki/ProjectPage',
              'discussion-link'
                  => 'https://www.mediawiki.org/wiki/Talk:ProjectPage',
          ];
      }
  }
}

Wiring up [developers]

[edit ]

Update your logic to show the feature so that it checks BetaFeatures::isFeatureEnabled (see isReadingListsEnabledForUser in ReadingLists for an example)

Deployment prep [PM]

[edit ]

Work with movement comms to announce beta feature and/or future deployment
For historic reasons let James Forrester know the beta feature is coming

Deployment [developers]

Register the beta feature in the allow list here: https://gerrit.wikimedia.org/r/c/operations/mediawiki-config/+/1148441/1/wmf-config/InitialiseSettings.php
Enable your feature flag.

Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:BetaFeatures/How_to_setup_a_beta_feature&oldid=8500465"