Jump to content

Extension:GrowthExperiments/Technical documentation

From mediawiki.org

Configuration

[edit]

GrowthExperiments extension can be configured at different levels:

Special:Homepage

[edit]

General overview: Growth/Personalized first day/Newcomer homepage

Special:Homepage is a special page that is the entry point for Growth features. Here are the available modules ("modules" is used more generically here as separate units of functionality, not to be confused with ResourceLoader modules).

Module Name Description Unactivated State Activated State
Banner Display on-wiki message ? ?
Start Email ? ? ?
Suggested edits Suggest editing tasks to users When the user hasn't clicked on the module, the Start Editing module is shown (desktop only) Task feed shown; filters can be updated
Start Editing Show filters for suggested edits inside the module itself (instead of in an overlay) N/A
Impact Show the page views and number of edits the user has done When the user hasn't made any edits, the heart graphic is shown with CTA to open suggested edits Editing statistics shown
Mentorship Allow the user to ask questions to their mentor and show past questions N/A
Mentorship Opt-in Allow the user to opt in to being mentored N/A
Help Show links to help articles N/A


Relevant files

ResourceLoader modules

  • ext.growthExperiments.Homepage.mobile
    • On mobile, some homepage module has two modes: mobile details and mobile summary. The summary mode is shown on Special:Homepage and the details mode is shown in an overlay (when JS is used, otherwise it is shown as a separate page; see T264992 for more details). This module sets up the overlays.
  • ext.growthExperiments.Homepage
    • JS files for modules that are always enabled (modules that are conditionally enabled are in separate ResourceLoader modules so that they can be conditionally included as well)
  • ext.growthExperiments.Homepage.Mentorship
  • ext.growthExperiments.Homepage.SuggestedEdits
  • ext.growthExperiments.Homepage.styles
    • CSS for server-side rendered modules (CSS for JS-only components are bundled with the respective ResourceLoader modules)

PHP

  • includes/Specials/SpecialHomepage.php
  • includes/HomepageHooks.php
  • includes/HomepageModules/
    • Construct HTML for each module
  • includes/Homepage/HomepageModuleRegistry.php
    • Handle dependency injection for each module

Suggested Edits

[edit]

General overview: Growth/Personalized first day/Newcomer tasks


"Suggested edits" is a module within Special:Homepage that provides users with editing tasks based on certain topics and difficulty levels. There are currently two types of tasks: unstructured and structured. Unstructured tasks are based on maintenance template(s) within an article (for example: " Tone " template for copyedit task). Structured tasks are based on machine suggestions (for example: images to be added to an article).


Relevant files

ResourceLoader modules

  • ext.growthExperiments.Homepage.SuggestedEdits
    • Enhance server-side rendered suggested edits module with the ability to select topics and task types via filters
  • ext.growthExperiments.SuggestedEditSession
    • Executed with each page load; used to keep track of whether the user is in the middle of a task or has just completed the task
  • ext.growthExperiments.PostEdit
    • Loaded via SuggestedEditSession; used to show a dialog after the user has completed a task
  • ext.growthExperiments.Homepage.mobile
    • Set up suggested edits mobile summary module
  • ext.growthExperiments.DataStore
    • Manage states for the task queue and the filters
    • Emit events when the state changes so that the UI can be updated (modeled after Vuex store)

PHP

  • includes/NewcomerTasks/
    • Generate the set of tasks for the user; handle task completion
  • includes/HomepageModules/
    • Server-side rendering of the suggested edits module
  • includes/HomepageHooks.php
    • Handle user preferences & opting users into Growth features
    • Output configuration variables needed by JavaScript code
    • Update navigation generated by skins to point to Special:Homepage
    • Generate virtual files needed by ResourceLoader modules


Features

  • Topic selection: The user can filter tasks by topics in which they are interested.
    • Topic selection is enabled via the configuration GEHomepageSuggestedEditsEnableTopics.
    • The topic of the article can be determined in two ways: "morelike" (based on search) and "ores". This can be configured via GENewcomerTasksTopicType.
      • "morelike" can be configured via GENewcomerTasksTopicConfigTitle and "ores" via GENewcomerTasksOresTopicConfigTitle.
    • When there are multiple topics selected, the results are matched to any of the selected topics (OR). To match all of the selected topics (AND), this feature can be enabled via GETopicsMatchModeEnabled.
  • Task type selection: The user can filter tasks by difficulty level (easy/medium/hard).
    • The difficulty level for each task type is specified in the MediaWiki page with title set via GENewcomerTasksConfigTitle.

Structured Tasks

[edit]

Impact module and Special:Impact

[edit]

General overview: Growth/Positive reinforcement

Impact module request workflow

[edit]

Special:Homepage

[edit]
  1. GET request to Special:Homepage via a browser
  2. getJsData in NewImpact.php checks if cached impact data is available.
    1. If the data is available, and the page view data is not stale (not older than 2 days), return it
    2. If the data is available but page view data is stale, don't export anything
    3. If the data is not available, don't export anything
  3. Vue application for NewImpact loads on client-side
  4. Client-side app starts to load data:
    1. If exported data is available from mw.config.get( 'homepagemodules' )['impact'], then it uses that
    2. If it is not available, the client-side app makes a POST request to `/growthexperiments/v0/user-impact/{user}`.
      1. UserImpactHandler receives the POST request, no data is available, ComputedUserImpactLookup will generate the impact data for the user, and save the updated information in a deferred update

Special:Impact

[edit]
  • TODO: Write this.

How we generate and store user impact data

[edit]
  • Each day, we run the refreshUserImpactData.php maintenance script with two different parameters. One run uses "--registeredWithin 2week --ignoreIfUpdatedWithin 6hour" and the other uses "--registeredWithin 1year --editedWithin 2week --ignoreIfUpdatedWithin 6hour"
    • The maintenance script calculates user impact data, including expensive to calculate information like page views. It caches the JSON representation of the calculated data in a database table, "growthexperiments_user_impact".
  • When a user visits Special:Homepage or Special:Impact, the NewImpact module makes an HTTP request to "/growthexperiments/v0/user-impact/{user}". The handler for this endpoint fetches data from the cache table, "growthexperiments_user_impact". If no data is found, it generates a new user impact data object, and saves it to the cache either with a deferred update (on POST) or via the job queue (on GET).
  • When a user makes an edit, or receives thanks from a user, we recalculate the user's impact data in a deferred update and update the entry in the cache table.
  • We run the deleteExpiredUserImpactData.php script daily, with the argument "--expiry 2days". That will remove entries in the "growthexperiments_user_impact" table that are older than 2 days.

d3.js

[edit]

GrowthExperiments uses a custom build of d3.js, optimized for size, by only including the sub-packages of d3 that we need to display charts and sparklines on the Impact module. The process for introducing d3 to GrowthExperiments is described in this post. The relevant files for updating the library are rollup.config.js, modules/lib/d3/index.js, and the devDependencies section of package.json. Run npm run rollup to generate the minified d3 build for use with the extension.

Help Panel

[edit]

General overview: Help:Growth/Tools/Help panel


The help panel provides help content when the user is doing an edit. It can be enabled via growthexperiments-help-panel-tog-help-panel preference. It's only available when JavaScript is enabled.

Entry Points

[edit]
  1. During suggested edit task — here the help panel is shown regardless of whether the editor is open or not
    • In this case, the help panel is enabled regardless of growthexperiments-help-panel-tog-help-panel preference since it is part of the suggested edits workflow.
  2. When editing an article (non-suggested edits) — here the help panel is only shown when the editor is open

Features

[edit]

Ask Help

The user can ask questions while editing. Depending on the configuration GEHelpPanelAskMentor, the question can be posed to the user's mentor or the help desk.


General Editing Help

The user can view links to help pages or how-to guides. The links shown are configured via GEHelpPanelLinks.


Task-specific Guidance

This feature is only available when the user is doing a suggested edit task (entry point #2). The guidance content is specific to the task type, the skin and the editor. Each wiki can technically override the guidance content by updating the message on-wiki. For example, to override the main message about copyedit task on Vector with VisualEditor, the message growthexperiments-help-panel-suggestededits-tips-vector-visualeditor-copyedit-main-value can be overridden on-wiki.


Link to Disable

If growthexperiments-help-panel-tog-help-panel is enabled, a link to Special:Preferences is shown.

Relevant files

[edit]

ResourceLoader modules

  • ext.growthExperiments.HelpPanel.init
    • Conditionally load ext.growthExperiments.HelpPanel module (used mainly for entry point #2)
  • ext.growthExperiments.HelpPanel
    • Set up the button for opening the help panel HelpPanelCta and event handlers for showing/hiding the button
    • Set up blue dot guidance
    • Conditionally load structured task modules (SuggestedEditsGuidance.js)
  • ext.growthExperiments.Help
    • Set up the contents of the help panel
    • Also used in ext.growthExperiments.Homepage.Mentorship since the ask help functionality is the same as in the mentorship module

PHP

  • includes/Rest/Handler/TipsHandler.php
    • Endpoint for retrieving task-specific guidance content
  • includes/HelpPanel/Tips/
    • Classes for generating task-specific guidance content
  • includes/HelpPanel/

Mentorship

[edit]

Tweaking the Special:EnrollAsMentor permission checks

[edit]

By default, only users with at least 500 edits who registered at least 90 days ago can use Special:EnrollAsMentor to become a mentor. At a local developer wiki, this can be an issue. Requirements for enrolling as a mentor can be changed using Community Configuration at Special:EditGrowthConfig (requires sysop permissions).

The requirements are defined in the "Mentorship" section of Special:EditGrowthConfig as:

  • "Minimum number of days a user must be registered to sign up as a mentor", and
  • "Minimum number of edits a user must have made (on any namespace) to sign up as a mentor".

To disable either of those checks, set it to zero.

At the same place, it is also possible to fully disable the automated permission changes. This, however, will remove mentorship access from all users, unless you alter LocalSettings.php as described under Alternative solutions.

Alternative solutions

[edit]
  • In the local database, update user_editcount and user_registration columns of the user table to higher/older values. Those columns are the source of truth for Special:EnrollAsMentor permission checks. This is useful for developers changing the implementation of the permission checks, or for writing test cases.
  • In LocalSettings.php, add $wgGroupPermissions['*']['enrollasmentor'] = true;. This will allow everyone to enroll as mentor, even though the requirements might not be met. If desired, instead of *, any other group name can be used, allowing only members of a certain group to enroll. This is used in Wikimedia production at wikis that want access to mentorship be governed by a manually assigned group, rather than an automated system.

Implementation notes

[edit]

The automated permission checks are implemented in includes/Mentorship/Hooks/MentorHooks.php using the UserGetRights hook.

Campaigns

[edit]

The GrowthExperiments extension has a set of features to support Campaigns in the Wikimedia community.

Features

[edit]

Customized Special:CreateAccount page

[edit]

The GrowthExperiments extension allows the creation of customized Special:CreateAccount pages.

Parameter Required? Documentation
campaign true The campaign pattern that will show the Special:CreateAccount campaign page. Example: 
campaign=social-campaign-2022
geEnabled false Whereas GrowthExperiments features should be enabled by default. Example: 
geEnabled=1
geForceVariant true Whereas the created account should force the user into an application variant. Example: 
geForceVariant=imagerecommendation

See Extension:GrowthExperiments/Technical_documentation#Structured_Tasks

Configuration

[edit]

List of configuration options

[edit]

Each configuration option is shown without the $wg prefix for brevity; add it when using, ie: $wgGECampaignPattern.

Option Default value Documentation
GECampaigns 
[]
Mapping of campaign ID to "topics", an array of topic IDs, and "pattern", a regexp for the campaign name, used to show campaign-specific topics in the suggested edits module. The topic IDs must have a corresponding search expression defined in GECampaignTopics. Examples can be found at Extension:GrowthExperiments/Technical_documentation/Special:EditGrowthConfig. 
[
'thankyoupage-2022' => [
		'pattern' => '/^typage-(latam|in|za)-en-2022$/',
        'qualityGateIdsToSkip' => [ 
          'image-recommendation' => [ 'dailyLimit' ]
         ],
		'skipWelcomeSurvey' => true,
		'signupPageTemplate' => 'hero',
		'signupPageTemplateParameters' => [
			'showBenefitsList' => 'desktop',
			'messageKey' => 'thankyoupage',
		 ],
        'topics' => [ 'argentina', 'mexico', 'chile']
    ]
]
  • pattern: {String} Regexp for campaign names which result in a special landing page for the given campaign
  • qualityGateIdsToSkip: {Array} Array of Structured Tasks IDs to determine whether the users registered within the campaign should have a limited number of add an image/add a link tasks per day
  • skipWelcomeSurvey: {Boolean} Boolean to determine whether the users registered within the campaign should get the welcome survey
  • signupPageTemplate: {String} One of ("hero", "video"). Determines which template to use for the Special:CreateAccount page. See designs: TBD.
  • signupPageTemplateParameters: {Array} Array of parameters for the signup template.
    • showBenefitList: {Boolean|String} One of (true, false, "desktop"). Determines whether to show the benefit list for the Special:CreateAccount page. If "desktop" is set, the list will only appear on desktop skin.
    • messageKey: {String} The text key infix to use for generating the campaign landing page texts. Example: TBD.
  • topics: An array of topic IDs (strings)
GECampaignTopics 
[]
Mapping of topic IDs to its search expression, used to show campaign-specific topics in the suggested edits module. Examples can be found at Extension:GrowthExperiments/Technical_documentation/Special:EditGrowthConfig. 
[
	'argentina' => 'growtharticletopic:argentina',
	'chile' => 'growtharticletopic:chile',
	'mexico' => 'growtharticletopic:mexico'
]

A/B tests, feature flags, and variants

[edit]

We often place new features behind a configuration flag. That allows us to merge patches related to a feature in small increments. Depending on how we implement the configuration flags, when we are ready, we can turn features on for all wikis, some subset of wikis, or some subset of users on a wiki.

Leveling up

[edit]

The GELevelingUpFeaturesEnabledflag gates features from the Growth team's Leveling Up project, which is a subset of the Growth/Positive_reinforcement project. The following features are included in wikis with GELevelingUpFeaturesEnabled set to true:

  • Post-edit dialog: Show a different state when no suggested edits are available (task T324177)
  • Post-edit: Show a "Try new task type" dialog on every 5th edit (T322386)
    • The frequency is determined by GELevelingUpManagerTaskTypeCountThresholdMultiple
  • Post-edit: When user completes a non-suggested edit, prompt them to try suggested edits on their 3rd and 7th article namespace edits (T322387)
    • The thresholds are determined by GELevelingUpManagerInvitationThresholds
  • Notifications: 48 hours after account creation, send a "keep going" notification to users who made 1-4 suggested edits (T328288)
    • The thresholds are determined by GELevelingUpKeepGoingNotificationThresholds
    • The "time to send after account creation" is determined by GELevelingUpKeepGoingNotificationSendAfterSeconds
  • Notifications: 48 hours after account creation, send a "get started" notification to users who have made zero suggested edits (T322435)
    • The "time to send after account creation" is determined by GELevelingUpGetStartedNotificationSendAfterSeconds

All Subpages

[edit]
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:GrowthExperiments/Technical_documentation&oldid=6008285"