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>Gergő Tisza
imported>Gergő Tisza
No edit summary
 
(2 intermediate revisions by one other user 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.


== Preparation ==
== Preparation ==
 
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]].
=== Some time ahead... ===
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]].


This can be omitted if needed.
This can be omitted if needed.


=== Server configuration (<code>operations/mediawiki-config</code>) ===
== Dark mode deployment ==
First, you need to 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>, ...).  You might also wish to set wmgGEFeaturesMayBeAvailableToNewcomers to false in case you are deploying the features in the dark mode (not available to newcomers).
Growth features are usually first deployed in so-called dark mode


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> in the <code>operations/mediawiki-config</code> repo and running <code>composer buildDBLists</code> (which updates <code>dblists/growthexperiments.dblist</code>).
=== Prepare patches ===
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>).


Once this is done, you need to configure the features. Overview of the configuration variables that are commonly set is below:
You also need to set <code>wmgGEFeaturesMayBeAvailableToNewcomers</code> to <code>false</code> to ensure features are not available to newcomers yet.
{| class="wikitable"
|+
!Feature
!Variable
!Mandatory/Optional
!Notes
|-
| rowspan="4" |Help panel
|<code>wgGEHelpPanelHelpDeskTitle</code>
|Optional
|
|-
|<code>wgGEHelpPanelLinks</code>
|Optional
|
*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>
*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).
* 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.
|-
|<code>wgGEHelpPanelReadingModeNamespaces</code>
|Optional
|
|-
|<code>wgGEHelpPanelViewMoreTitle</code>
|Mandatory
|
|-
| rowspan="2" |Homepage
|<code>wgGEHomepageMentorsList</code>
|Optional
|
|-
|<code>wgGEHomepageSuggestedEditsIntroLinks</code>
|Mandatory
|
|}


=== Wiki configuration ===
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.
On-wiki config needs to be done in <code>MediaWiki:NewcomerTasks.json</code>. You can copy&customize [[w:cs:MediaWiki:NewcomerTasks.json|Czech Wikipedia's copy]] to do this easily; for more details see the documentation of <code>$wgGENewcomerTasksConfigTitle</code>. This means your wiki account needs to be in staff, sysop or a similar user group. 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>


=== Deployment ===
=== Deployment ===
Deploy the changes in a [[Backport windows|backport window]]. After you do so, please:
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.
 
# 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.
# Merge the prepared configuration patch and fetch it to the deployment server.
# ssh to maintenance server and pull the patch there via <code>scap pull</code>.
# Initialize the on-wiki config via running <code>mwscript extensions/GrowthExperiments/maintenance/initWikiConfig.php --wiki='''xx'''wiki --phab=T'''xxxxx'''</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.
# 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.


# ''(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='''XX'''wiki 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='''XX'''wiki</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]]


== 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 <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.
**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. <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.)
[[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

Retrieved from "https://wikitech-static.wikimedia.org/w/index.php?title=GrowthExperiments_setup&oldid=586785"