Extension:GrowthExperiments/Technical documentation
Configuration
editGrowthExperiments extension can be configured at different levels:
- (Privileged users) Editing configuration settings in LocalSettings.php . For a complete list of GrowthExperiments configuration settings see TBD
- (Privileged users) Changing configuration settings available through the Extension:GrowthExperiments/Technical_documentation/Special:EditGrowthConfig
- (Users) Users can enable and disable some of the GrowthExperiments features using their on-wiki preferences.
Special:Homepage
editGeneral 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 task 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
editGeneral 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" viaGENewcomerTasksOresTopicConfigTitle
.
- "morelike" can be configured via
- 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
.
- Topic selection is enabled via the configuration
- 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
.
- The difficulty level for each task type is specified in the MediaWiki page with title set via
Structured Tasks
editImpact module and Special:Impact
editGeneral overview: Growth/Positive reinforcement
Impact module request workflow
editSpecial:Homepage
edit- GET request to Special:Homepage via a browser
- getJsData in NewImpact.php checks if cached impact data is available.
- If the data is available, and the page view data is not stale (not older than 2 days), return it
- If the data is available but page view data is stale, don't export anything
- If the data is not available, don't export anything
- Vue application for NewImpact loads on client-side
- Client-side app starts to load data:
- If exported data is available from mw.config.get( 'homepagemodules' )['impact'], then it uses that
- If it is not available, the client-side app makes a POST request to `/growthexperiments/v0/user-impact/{user}`.
- 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
editGrowthExperiments 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
editGeneral 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- 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.
- In this case, the help panel is enabled regardless of
- When editing an article (non-suggested edits) — here the help panel is only shown when the editor is open
Features
editAsk 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
editResourceLoader modules
ext.growthExperiments.HelpPanel.init
- Conditionally load
ext.growthExperiments.HelpPanel
module (used mainly for entry point #2)
- Conditionally load
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
)
- Set up the button for opening the help panel
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
editTweaking the Special:EnrollAsMentor permission checks
editBy 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
anduser_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
editThe automated permission checks are implemented in includes/Mentorship/Hooks/MentorHooks.php
using the UserGetRights hook.
Campaigns
editThe GrowthExperiments extension has a set of features to support Campaigns in the Wikimedia community.
Features
editCustomized Special:CreateAccount page
editThe 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
editList of configuration options
editEach 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']
]
]
|
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
editWe 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
editThe GELevelingUpFeaturesEnabled
flag 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 (task T322386)
- The frequency is determined by
GELevelingUpManagerTaskTypeCountThresholdMultiple
- The frequency is determined by
- Post-edit: When user completes a non-suggested edit, prompt them to try suggested edits on their 3rd and 7th article namespace edits (task T322387)
- The thresholds are determined by
GELevelingUpManagerInvitationThresholds
- The thresholds are determined by
- Notifications: 48 hours after account creation, send a "keep going" notification to users who made 1-4 suggested edits (task T328288)
- The thresholds are determined by
GELevelingUpKeepGoingNotificationThresholds
- The "time to send after account creation" is determined by
GELevelingUpKeepGoingNotificationSendAfterSeconds
- The thresholds are determined by
- Notifications: 48 hours after account creation, send a "get started" notification to users who have made zero suggested edits (task T322435)
- The "time to send after account creation" is determined by
GELevelingUpGetStartedNotificationSendAfterSeconds
- The "time to send after account creation" is determined by
All Subpages
edit- GrowthExperiments/Technical documentation/Campaigns/Creation of customized landing pages
- GrowthExperiments/Technical documentation/Coding conventions
- GrowthExperiments/Technical documentation/Community Configuration migration
- GrowthExperiments/Technical documentation/Frontend
- GrowthExperiments/Technical documentation/Special:EditGrowthConfig
- GrowthExperiments/Technical documentation/Structured tasks
- GrowthExperiments/Technical documentation/Structured tasks/Add a link
- GrowthExperiments/Technical documentation/Structured tasks/Add a section image
- GrowthExperiments/Technical documentation/Structured tasks/Add an image