GrowthExperiments setup/Old

From Wikitech
Those are the old instructions. They should still work, and you can use them if something goes wrong, but GrowthExperiments setup has the newest documentation.

This is a documentation for developers for adding Growth features to a Wikimedia wiki. For requesting these features as a community member, see mw:Growth/Communities/Get the Growth experiments on your wiki instead.

Preparation

Some time ahead...

Add special page aliases for the new language. (Example patch: 643084 Note: do not include namespace names.) Unlike the other changes described here, this is deployed via the train so it's worth doing ahead of the rest. This is an i18n change so if you need to backport it, you have to use scap sync-world.

This can be omitted if needed.

Server configuration (operations/mediawiki-config)

First, you need to enable the extension itself (wmgUseGrowthExperiments). This enables all main features. In rare cases, some might need to be disabled for the wiki (wgWelcomeSurveyEnabled, wgGEHelpPanelEnabled, wgGEHomepageEnabled, ...). You might also wish to set wmgGEFeaturesMayBeAvailableToNewcomers to false in case you are deploying the features in the dark mode (not available to newcomers).

In addition to wmgUseGrowthExperiments, you need to add the wiki to the growthexperiments dblist by adding growthexperiments to the inheritsFrom list in wmf-config/config/{wiki id}.yaml in the operations/mediawiki-config repo and running composer buildDBLists (which updates dblists/growthexperiments.dblist).

Once this is done, you need to configure the features. Overview of the configuration variables that are commonly set is below:

Feature Variable Mandatory/Optional Notes
Help panel wgGEHelpPanelHelpDeskTitle Optional
wgGEHelpPanelLinks Optional
  • The title field is the page title of the wiki page to link to. Interwiki prefixes and section fragments can be used here, e.g. mw:Help/VisualEditor/User_guide/pt#Editar_referências
  • The text field is the link text. The Phabricator task requesting the deployment should specify both the title and the text for each link, but it sometimes doesn't. If the text is not specified, you can usually the page title without namespace, but use your best judgement and ask the requesting community member to confirm your guesses. Use spaces not underscores (everywhere else it doesn't matter).
  • The id field is somewhat arbitrary (only used for analytics), you can try to follow conventions from other languages but ultimately it doesn't matter much.
wgGEHelpPanelReadingModeNamespaces Optional
wgGEHelpPanelViewMoreTitle Mandatory
Homepage wgGEHomepageMentorsList Optional
wgGEHomepageSuggestedEditsIntroLinks Mandatory

Wiki configuration

On-wiki config needs to be done in MediaWiki:NewcomerTasks.json. You can copy&customize Czech Wikipedia's copy to do this easily; for more details see the documentation of $wgGENewcomerTasksConfigTitle. This means your wiki account needs to be in staff, sysop or a similar user group. Use a descriptive edit summary such as Configuration for [[mw:Growth/Personalized first day/Newcomer homepage]]. See [[phab:XXX]] for more information.

Deployment

Before you start deploying, mwscript extensions/WikimediaMaintenance/createExtensionTables.php --wiki=XXwiki GrowthExperiments. This is important, as it will create necessary database tables. !log the table creation.

Once you created the tables, deploy the changes in a backport window. After you do so, please:

  1. Test by enabling User profile > Display newcomer homepage and Editing > Enable the editor help panel in Special:Preferences, visiting Special:ClaimMentee (this will validate the mentor page as a side effect), visiting Special:Homepage, and clicking on a suggested task to bring up the help panel in suggested editing mode.
  2. Check that there are enough tasks, by running mwscript extensions/GrowthExperiments/maintenance/listTaskCounts.php --wiki=XXwiki. It's especially important for the copyedit and links task types to have some tasks for each topic.
    • Ideally, we would check whether there are enough tasks before deployment, but we don't have the tooling for that yet.

Validation of translations (back-up from old docs)

Verify that the translations are complete. You should also do this ahead of the other steps, so that translators have time to add any missing translations.

  • Add the new language to the requireCompleteTranslationLanguages array in Gruntfile.js in the GrowthExperiments repo (example patch)
  • Run grunt banana:translations. This will output a list of message keys for each language with missing translations.
    • Note that the list is grouped first by i18n subdirectory, then by language, so the missing messages for each language may be split across multiple lists
    • Optional messages that don't have to be translated are also listed as missing, so there are a few false positives. You can check whether a message is optional in qqq, and you can get an idea of which messages are likely to be false positives by looking at which messages are reported as missing in almost every language, and/or in languages with very few missing translations
  • It's recommended that you wait until most or all translations have been completed and have been deployed via the train
    • When you're not sure which translations caught the train, you can check by checking out the relevant wmf branch (e.g. git checkout wmf/1.36.0-wmf.22) and running grunt banana:translations
    • Backporting translation changes is possible, but is recommended against because it requires usng scap sync-world. If the number of translations that missed the train is small, consider using temporary overrides in the MediaWiki namespace instead. (If message growthexperiments-foo is missing, copy+paste its translation into the MediaWiki:Growthexperiments-foo wiki page, then set a reminder to delete that page after the translation has been deployed via the train.)