Extension:GrowthExperiments/Technical documentation

Configuration
GrowthExperiments extension can be configured at different levels:


 * (Privileged users) Editing configuration settings in . 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
General overview: Growth/Personalized first day/Newcomer 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).

Relevant files

ResourceLoader modules


 * 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 for more details). This module sets up the overlays.
 * 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)
 * CSS for server-side rendered modules (CSS for JS-only components are bundled with the respective ResourceLoader modules)
 * 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)
 * CSS for server-side rendered modules (CSS for JS-only components are bundled with the respective ResourceLoader modules)
 * CSS for server-side rendered modules (CSS for JS-only components are bundled with the respective ResourceLoader modules)
 * CSS for server-side rendered modules (CSS for JS-only components are bundled with the respective ResourceLoader modules)
 * CSS for server-side rendered modules (CSS for JS-only components are bundled with the respective ResourceLoader modules)

PHP


 * Construct HTML for each module
 * Handle dependency injection for each module
 * Construct HTML for each module
 * Handle dependency injection for each module
 * Handle dependency injection for each module
 * Handle dependency injection for each module

Suggested Edits
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


 * Enhance server-side rendered suggested edits module with the ability to select topics and task types via filters
 * 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
 * Loaded via SuggestedEditSession; used to show a dialog after the user has completed a task
 * Set up suggested edits mobile summary module
 * 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)
 * Set up suggested edits mobile summary module
 * 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)
 * 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


 * Generate the set of tasks for the user; handle task completion
 * Server-side rendering of the suggested edits module
 * 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
 * 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.
 * The topic of the article can be determined in two ways: "morelike" (based on search) and "ores". This can be configured via.
 * "morelike" can be configured via  and "ores" 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.
 * 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.

Structured Tasks

 * Overview of how structured tasks integrate with VisualEditor
 * Add a link
 * Add an image / Add an image to a section
 * Diagrams for the structured tasks backend

Impact module and Special:Impact
General overview: Growth/Positive reinforcement

Special:Homepage

 * 1) GET request to Special:Homepage via a browser
 * 2) getJsData in NewImpact.php checks if cached impact data is available.
 * 3) If the data is available, and the page view data is not stale (not older than 2 days), return it
 * 4) If the data is available but page view data is stale, don't export anything
 * 5) If the data is not available, don't export anything
 * 6) Vue application for NewImpact loads on client-side
 * 7) Client-side app starts to load data:
 * 8) If exported data is available from mw.config.get( 'homepagemodules' )['impact'], then it uses that
 * 9) If it is not available, the client-side app makes a POST request to `/growthexperiments/v0/user-impact/{user}`.
 * 10) 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

 * TODO: Write this.

How we generate and store user impact data

 * 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
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,  , and the   section of. Run  to generate the minified d3 build for use with the extension.

Help Panel
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  preference. It's only available when JavaScript is enabled.

Entry Points

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

Features
Ask Help

The user can ask questions while editing. Depending on the configuration, 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.

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  can be overridden on-wiki.

Link to Disable

If  is enabled, a link to Special:Preferences is shown.

Relevant files
ResourceLoader modules


 * Conditionally load  module (used mainly for entry point #2)
 * Set up the button for opening the help panel  and event handlers for showing/hiding the button
 * Set up blue dot guidance
 * Conditionally load structured task modules
 * Set up the contents of the help panel
 * Also used in  since the ask help functionality is the same as in the mentorship module
 * Set up the contents of the help panel
 * Also used in  since the ask help functionality is the same as in the mentorship module
 * Also used in  since the ask help functionality is the same as in the mentorship module

PHP


 * Endpoint for retrieving task-specific guidance content
 * Classes for generating task-specific guidance content
 * Classes for generating task-specific guidance content
 * Classes for generating task-specific guidance content

Tweaking the Special:EnrollAsMentor permission checks
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

 * In the local database, update  and   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 . 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
The automated permission checks are implemented in  using the UserGetRights hook.

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

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

List of configuration options
Each configuration option is shown without the  prefix for brevity; add it when using, ie:.

A/B tests, feature flags, and variants
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
The 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  set to  :


 * Post-edit dialog: Show a different state when no suggested edits are available
 * Post-edit: Show a "Try new task type" dialog on every 5th edit
 * 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
 * The thresholds are determined by
 * Notifications: 48 hours after account creation, send a "keep going" notification to users who made 1-4 suggested edits
 * The thresholds are determined by
 * The "time to send after account creation" is determined by
 * Notifications: 48 hours after account creation, send a "get started" notification to users who have made zero suggested edits
 * The "time to send after account creation" is determined by