You are browsing a read-only backup copy of Wikitech. The live site can be found at wikitech.wikimedia.org

GrowthExperiments setup: Difference between revisions

From Wikitech-static
Jump to navigation Jump to search
imported>Urbanecm
(typo)
imported>Gergő Tisza
No edit summary
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Note|content=If something goes wrong, [[GrowthExperiments setup/Old]] has the old, manual instructions.}}
This is a documentation for developers for adding [[mw:Growth|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.
This is a documentation for developers for adding [[mw:Growth|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.


# Add [[mw:Manual:Special_pages#The_aliases_file|special page aliases]] for the new language. (Example patch: {{gerrit|643084}} Note: do not include namespace names.) Unlike the other changes described here, this is deployed via the [[Deployments/Train|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#scap_sync-world|scap sync-world]].
== Preparation ==
# 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 special page aliases for the new language. (Example patch: {{gerrit|643084}} Note: do not include namespace names.) Unlike the other changes described here, this is deployed via the [[Deployments/Train|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#scap%20sync-world|scap sync-world]].
#*Add the new language to the <code>requireCompleteTranslationLanguages</code> array in <code>Gruntfile.js</code> in the GrowthExperiments repo ([[gerrit:c/mediawiki/extensions/GrowthExperiments/+/609885|example patch]])
 
#*Run <code>grunt banana:translations</code>. This will output a list of message keys for each language with missing translations.
This can be omitted if needed.
#**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
== Dark mode deployment ==
#*It's recommended that you wait until most or all translations have been completed and have been deployed via the train
Growth features are usually first deployed in so-called dark mode
#**When you're not sure which translations caught the train, you can check by checking out the relevant wmf branch (e.g. <code>git checkout wmf/1.36.0-wmf.22</code>) and running <code>grunt banana:translations</code>
 
#**Backporting translation changes is possible, but is recommended against because it requires usng [[Scap#scap_sync-world|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 <code>growthexperiments-foo</code> is missing, copy+paste its translation into the <code>MediaWiki:Growthexperiments-foo</code> wiki page, then set a reminder to delete that page after the translation has been deployed via the train.)
=== Prepare patches ===
# Update [[InitialiseSettings.php]] in the <code>[https://gerrit.wikimedia.org/r/plugins/gitiles/operations/mediawiki-config operations/mediawiki-config]</code> repo (example patch: {{gerrit|634119}}):
In <code>wmf-config/InitialiseSettings.php</code> (can be found in <code>operations/mediawiki-config</code> repository), you will need to enable <code>wmgUseGrowthExperiments</code>. In addition to <code>wmgUseGrowthExperiments</code>, you need to add the wiki to the growthexperiments [[Configuration_files#dblists|dblist]] by adding <code>growthexperiments</code> to the <code>inheritsFrom</code> list in <code>wmf-config/config/{wiki id}.yaml</code> same repo (run <code>composer buildDBLists</code> to update <code>dblists/growthexperiments.dblist</code>).
#* Enable the extension itself (<code>wmgUseGrowthExperiments</code>). This enables all main features; in rare cases, some might need to be disabled for the wiki (<code>wgWelcomeSurveyEnabled</code>, <code>wgGEHelpPanelEnabled</code>, <code>wgGEHomepageEnabled</code>).
 
#* Set various configuration options. (Many of these are strings in the wiki's language. Note that some text editors, especially console-based ones like vim, mess up some non-Latin scripts in all kinds of exciting ways. Copy-pasting is usually safe in any Unicode-aware editor; editing the pasted text, not necessarily so.) The commonly used ones correlate with the fields in the standard task template as follows:
You also need to set <code>wmgGEFeaturesMayBeAvailableToNewcomers</code> to <code>false</code> to ensure features are not available to newcomers yet.
#** Help panel:
 
#*** Help desk: <code>wgGEHelpPanelHelpDeskTitle</code>
This part can be done ahead of actual deployment, and does not require any permissions apart from having a developer account. Rest of the instructions require deployment access.
#*** Help pages: <code>wgGEHelpPanelLinks</code>
 
#**** The <code>title</code> field is the page title of the wiki page to link to. Interwiki prefixes and section fragments can be used here, e.g. <code>mw:Help/VisualEditor/User_guide/pt#Editar_referências</code>
=== Deployment ===
#****The <code>text</code> 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).
It is recommended to proceed only if you are comfortable with editing on-wiki config files (for that, +staff or similar access is needed), if necessary. If everything goes all right, it should not be needed, but the need might arise.
#**** The <code>id</code> field is somewhat arbitrary (only used for analytics), you can try to follow conventions from other languages but ultimately it doesn't matter much.
 
#*** Search on namespace: <code>wgGEHelpPanelReadingModeNamespaces</code>. Only set if it includes something other than the default (Wikipedia and Help).
Usually, the deployment is done as part of a [[backport window]] (without booking a dedicated window) – the scripts should not be time consuming.
#*** Read more about editing: <code>wgGEHelpPanelViewMoreTitle</code>
 
#** Homepage:
# Run <code>mwscript extensions/WikimediaMaintenance/createExtensionTables.php --wiki='''XX'''wiki GrowthExperiments</code>. This is '''important''', as it will create necessary database tables. <code>!log</code> the table creation.
#*** Tutorial: <code>wgGEHomepageTutorialTitle</code>
# Merge the prepared configuration patch and fetch it to the deployment server.
#*** Signature list: <code>wgGEHomepageMentorsList</code>
# ssh to maintenance server and pull the patch there via <code>scap pull</code>.
#** Suggested edits:
# Initialize the on-wiki config via running <code>mwscript extensions/GrowthExperiments/maintenance/initWikiConfig.php --wiki='''xx'''wiki --phab=T'''xxxxx'''</code>
#*** Additional links: <code>wgGEHomepageSuggestedEditsIntroLinks</code>
# Go to https://xx.wikipedia.org/wiki/MediaWiki:GrowthExperimentsConfig.json and https://xx.wikipedia.org/wiki/MediaWiki:NewcomerTasks.json and verify the configuration looks fine.
#*** See below for task-specific settings.
# Deploy the patch using instructions at [[Backport windows/Deployers]].
# Add the wiki to the growthexperiments [[Configuration_files#dblists|dblist]] by adding <code>growthexperiments</code> to the <code>inheritsFrom</code> list in <code>wmf-config/config/{wiki id}.yaml</code> in the <code>mediawiki/operations-config</code> repo and running <code>composer buildDBLists</code> (which updates <code>dblists/growthexperiments.dblist</code>). This is usually done in the same patch as the <code>InitialiseSettings.php</code> changes - in general this is a bad idea as changes in one file might depend on the other, but specifically for GrowthExperiments the dblist does not do anything important so this is OK.
 
# Add on-wiki configuration. This is done on the <code>MediaWiki:NewcomerTasks.json</code> page (example: [[w:fr:MediaWiki:NewcomerTasks.json]]), which means your wiki account needs to be in staff, sysop or a similar user group. The contents correlate to table in the Suggested edits section of the standard task template. Use a descriptive edit summary such as <code>Configuration for <nowiki>[[mw:Growth/Personalized first day/Newcomer homepage]]</nowiki>. See <nowiki>[[phab:XXX]]</nowiki> for more information.</code>
=== Verification ===
# Deploy the config change in a [[Backport windows|backport window]].
To ensure the features work, go to the wiki, enable newcomer dashboard and editor help panel in your preferences and go to Special:Homepage. You can also see the number of tasks available at https://xx.wikipedia.org/wiki/Special:NewcomerTaskInfo.
## ''(Placeholder for adding tables. This is not needed today, but by the time this page is next used, it probably will be.)'' Run <code>mwscript extensions/WikimediaMaintenance/createExtensionTables.php --wiki=xxwiki GrowthExperiments</code>
 
## 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.
# 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.
##Check that there are enough tasks, by running <code>mwscript extensions/GrowthExperiments/maintenance/listTaskCounts.php --wiki=xxwiki</code>. It's especially important for the <code>copyedit</code> and <code>links</code> task types to have some tasks for each topic.
#Check that there are enough tasks, by going to https://xx.wikipedia.org/wiki/Special:NewcomerTaskInfo. It's especially important for the <code>copyedit</code> and <code>links</code> 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,
#*Ideally, we would check whether there are enough tasks before deployment, but we don't have the tooling for that yet.
 
== See also ==
* [[Add Link]]
* [[Add Image]]


[[Category:How-To]]
[[Category:How-To]]

Latest revision as of 07:07, 19 February 2022

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

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.

Dark mode deployment

Growth features are usually first deployed in so-called dark mode

Prepare patches

In wmf-config/InitialiseSettings.php (can be found in operations/mediawiki-config repository), you will need to enable wmgUseGrowthExperiments. 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 same repo (run composer buildDBLists to update dblists/growthexperiments.dblist).

You also need to set wmgGEFeaturesMayBeAvailableToNewcomers to false to ensure features are not available to newcomers yet.

This part can be done ahead of actual deployment, and does not require any permissions apart from having a developer account. Rest of the instructions require deployment access.

Deployment

It is recommended to proceed only if you are comfortable with editing on-wiki config files (for that, +staff or similar access is needed), if necessary. If everything goes all right, it should not be needed, but the need might arise.

Usually, the deployment is done as part of a backport window (without booking a dedicated window) – the scripts should not be time consuming.

  1. Run mwscript extensions/WikimediaMaintenance/createExtensionTables.php --wiki=XXwiki GrowthExperiments. This is important, as it will create necessary database tables. !log the table creation.
  2. Merge the prepared configuration patch and fetch it to the deployment server.
  3. ssh to maintenance server and pull the patch there via scap pull.
  4. Initialize the on-wiki config via running mwscript extensions/GrowthExperiments/maintenance/initWikiConfig.php --wiki=xxwiki --phab=Txxxxx
  5. Go to https://xx.wikipedia.org/wiki/MediaWiki:GrowthExperimentsConfig.json and https://xx.wikipedia.org/wiki/MediaWiki:NewcomerTasks.json and verify the configuration looks fine.
  6. Deploy the patch using instructions at Backport windows/Deployers.

Verification

To ensure the features work, go to the wiki, enable newcomer dashboard and editor help panel in your preferences and go to Special:Homepage. You can also see the number of tasks available at https://xx.wikipedia.org/wiki/Special:NewcomerTaskInfo.

  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 going to https://xx.wikipedia.org/wiki/Special:NewcomerTaskInfo. 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.

See also