Phabricator project: #Flow

Extension:Flow

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
Flow

Release status: beta

2013-08-21 Flow prototype.png
Implementation Notify
Description Provides a new discussion and collaboration system for talk pages
Author(s) Brandon Harris, Erik Bernhardson, Matthias Mullie, Andrew Garrett, Benny Situ, Shahyar Ghobadpour, Matthew Flaschen, Roan Kattouw, Moriel Schottlender, Stephane Bisson, Kunal Mehta
Latest version 1.1
MediaWiki 1.24+ (Flow master is only supported with core's master; otherwise, use Flow REL_1_24 with core REL_1_24 or matching WMF release branches).
PHP 5.3.6+
Database changes Yes
License GPL
Download
Example Talk:Flow
Added rights

flow-hide, flow-edit-post, flow-create-board, flow-suppress, flow-delete, flow-lock

Hooks used
LoadExtensionSchemaUpdates

ApiTokensGetTokenTypes
MediaWikiPerformAction
OldChangesListRecentChangesLine
SkinTemplateNavigation::Universal
Article::MissingArticleConditions
SpecialWatchlistGetNonRevisionTypes
UserGetReservedNames
ResourceLoaderGetConfigVars
ContribsPager::reallyDoQuery
ContributionsLineEnding
AbuseFilter-computeVariable

Translate the Flow extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

Issues:

Open tasks · Report a bug

The Flow extension provides a new discussion and collaboration system for talk pages

See Flow for an overview of what this extension is planned to address over time and try it out.

Installing[edit | edit source]

Caution! Caution: This is in Beta and still under active development. You may want to drop into #wikimedia-collaborationconnect to discuss before installing.

The easiest way to install Flow is to use the MediaWiki-Vagrant appliance and enable its flow role.

To install the extension manually:

  • Download and place the file(s) in a directory called Flow in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
require_once "$IP/extensions/Flow/Flow.php";
  • Run the update script which will automatically create the necessary database tables that this extension needs.
  • YesYDone - Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Note Note: Running "update.php" can leave temporary /tmp/mw-UIDGeneratorUUID-UID-xx files that MediaWiki may be unable to open (phab:T55791). If you get a "Permission denied" error upon first visiting a Flow board you have to delete these files. Also, update.php will create {{FlowMention}} to support Flow's mention feature in VE (either @ or a toolbar menu provides a convenient auto-complete interface for mentions).

Dependencies[edit | edit source]

  • required: Extension:Echo for notifications (e.g. replies to your post)
  • required: It is recommended to use memcached as your cache. You may encounter problems with Redis currently.
  • required/optional: Parsoid for the option to store posts as HTML ($wgFlowContentFormat = 'html';) which improves performance. This is how WMF wikis are configured, and hence is the most tested configuration. As of September 2014 it is required, there are bugs with format 'wikitext', e.g. task T72148. If you use MediaWiki-Vagrant, enabling Flow enables Parsoid and sets the format to 'html'.
  • optional: Extension:CLDR for human-friendly timestamps such as "3 days ago"
  • optional: Extension:VisualEditor for VisualEditor support ($wgFlowEditorList = array( 'visualeditor', 'none' );)
    bug? if you have the VisualEditor present (e.g. perhaps to provide OOjs UI),then Flow will attempt to contact Parsoid even if VE is not enabled
  • optional: Flow can integrate with Extension:AbuseFilter, Extension:SpamBlacklist, and Extension:ConfirmEdit, see /Spam
  • optional: Extension:Thanks to "Thank" users for their posts (requires Echo)
  • optional: Extension:EventLogging for analytics

Only for REL_1_24[edit | edit source]

Verifying installation[edit | edit source]

Visit one of the pages you enabled for Flow (see #Configuration) and try adding a topic and editing its header.

Upgrading[edit | edit source]

$wgFlowOccupyPages was removed as part of phab:T105574. Before upgrading to a version without this functionality, run:

php maintenance/populateContentModel.php --ns=all --table=page
php extensions/Flow/maintenance/FlowUpdateRevContentModelFromOccupyPages.php

The first one is from core.

Configuration[edit | edit source]

Here are some settings you need to make in LocalSettings.php.

Enabling Flow[edit | edit source]

To enable Flow for a namespace, use $wgNamespaceContentModels. For example:

  // These lines enable Flow on the "Project talk" and "User talk" namespaces
  $wgNamespaceContentModels[NS_PROJECT_TALK] = CONTENT_MODEL_FLOW_BOARD;
  $wgNamespaceContentModels[NS_USER_TALK] = CONTENT_MODEL_FLOW_BOARD;

To enable it on a single page, use Special:EnableFlow. This requires the flow-create-board right, which can be granted to any group (see Manual:User rights#Changing group permissions).

  $wgGroupPermissions['somegroup']['flow-create-board'] = true;

Parsoid configuration[edit | edit source]

If your wiki loads the VisualEditor extension, then the values you specify for Flow's Parsoid configuration variables $wgFlowParsoidPrefix/Timeout/URL should probably match VisualEditor's equivalent variables ($wgVisualEditorParsoidPrefix/Timeout/URL).

"maximum function nesting level of '100' reached, aborting"[edit | edit source]

If you get this error, you need to set xdebug.max_nesting_level = 200, probably in /etc/php5/apache2/php.ini .[1]

"Exception Caught: CAS is not implemented in Xyz"[edit | edit source]

Flow invokes $cache->cas() and some cache implementations including CACHE_ACCEL (APCBagOStuff) don't implement CAS. You probably need to use a different cache, for example install memcached and set $wgMainCacheType = CACHE_MEMCACHED;.

Permissions[edit | edit source]

Users must have the core edit permission to perform any write action in Flow. Many wikis only grant this permission to the 'user' (logged-in) or 'autoconfirmed' group.

Flow defines many actions such as edit-post and delete-topic (see the list in FlowActions.php). The permissions vary depending on whether the post is your own and whether it has been moderated. For example, by default users can edit their own posts, but only users in the 'sysop' group have the flow-edit-post permission to edit anyone's post. You can override which groups have which permissions and what permissions are required for each Flow action; see Manual:User rights for an overview of permissions.

Migrating existing pages[edit | edit source]

To migrate a single existing page, use Special:EnableFlow. It will handle archiving of a single page (then enabling Flow) automatically.

The script maintenance/convertNamespaceFromWikitext.php automates this namespace conversion and archiving, see Flow/Converting talk pages. It is somewhat WMF-specific, so evaluate its operation and backup your database before running it. Another script maintenance/convertLqt.php converts LiquidThreads pages and their threads to Flow boards and topics, see Flow/Converting LiquidThreads. Similar caveats apply.

Flow adds a Topic: namespace, see Extension default namespaces#Flow. You can visit Special:PrefixIndex/Topic: to see if there are existing pages that conflict with this; if so run the maintenance script maintenance/namespaceDupes.php.

Configuration[edit | edit source]

Configuration settings in Flow.php
parameter default comment
$wgFlowHelpPage //www.mediawiki.org/wiki/Special:MyLanguage/Help:Extension:Flow URL for more information about the Flow notification system
$wgFlowCluster false $wgFlowCluster will define what external DB server should be used.

If set to false, the current database (wfGetDB) will be used to read/write data from/to. If Flow data is supposed to be stored on an external database, set the value of this variable to the $wgExternalServers key representing that external connection.

$wgFlowDefaultWikiDb false Database to use for Flow metadata. Set to false to use the wiki db.

Any number of wikis can and should share the same Flow database.

$wgFlowExternalStore false Used for content storage. False to store content in flow db. Otherwise a cluster or list of clusters to use with ExternalStore. Provided clusters must exist $wgExternalStores.

Multiple clusters required for HA, so inserts can continue if one of the masters is down for maint or any other reason.

$wgFlowExternalStore = array( 'DB://cluster24', 'DB://cluster25' );

$wgFlowContentFormat html By default, Flow will store content in HTML. However, this requires having Parsoid up and running, as it'll be necessary to convert HTML to wikitext for the basic editor. (n.b. to use VisualEditor, you'll definitely need Parsoid, so if you do support VE, might as well set this to HTML right away)

If $wgFlowParsoidURL is null, $wgFlowContentFormat will be forced to wikitext.

The 'wikitext' format is likely to be deprecated in the future.

$wgFlowParsoidURL null Flow Parsoid config

Please note that this configuration is separate from VE's Parsoid config: you'll have to fill out these variables too if you want to use Parsoid.

$wgFlowParsoidPrefix null Flow Parsoid config

Please note that this configuration is separate from VE's Parsoid config: you'll have to fill out these variables too if you want to use Parsoid.

$wgFlowParsoidTimeout null Flow Parsoid config

Please note that this configuration is separate from VE's Parsoid config: you'll have to fill out these variables too if you want to use Parsoid.

$wgFlowParsoidForwardCookies false Forward users' Cookie: headers to Parsoid. Required for private wikis (login required to read).

If the wiki is not private (i.e. $wgGroupPermissions['*']['read'] is true) this configuration variable will be ignored.

This feature requires a non-locking session store. The default session store will not work and will cause deadlocks when trying to use this feature. If you experience deadlock issues, enable $wgSessionsInObjectCache.

WARNING: ONLY enable this on private wikis and ONLY IF you understand the SECURITY IMPLICATIONS of sending Cookie headers to Parsoid over HTTP. For security reasons, it is strongly recommended that $wgVisualEditorParsoidURL be pointed to localhost if this setting is enabled.

$wgFlowDefaultWorkflow discussion When visiting the flow for an article but not specifying what type of workflow should be viewed, use this workflow
$wgFlowDefaultLimit 10 Limits for paging
$wgFlowMaxLimit 100 Limits for paging
$wgFlowMaxMentionCount 100 Maximum number of users that can be mentioned in one comment
$wgFlowMaxThreadingDepth 8 Max threading depth
$wgFlowEditorList array( 'visualeditor', 'wikitext' ); ) A list of editors to use, in priority order. Non-supported editors will be skipped.
$wgFlowUseMemcache true Set this to false to disable all memcache usage. Do not just turn the cache back on, it will be out of sync with the database. There is not yet an official process for re-sync'ing the cache yet, currently the per-index versions would need to incremented(ask the flow team).

This will reduce, but not necessarily kill, performance. The queries issued will be the queries necessary to fill the cache rather than only the queries needed to answer the request. A bit of a refactor in ObjectManager::findMulti to allow query without indexes, along with adjusting container.php to only include the indexes when this is true, would get most of the way towards making this a reasonably performant option.

$wgFlowCacheTime 60 * 60 * 24 * 3 The default length of time to cache flow data in memcache. This value can be tuned in conjunction with measurements of cache hit/miss ratios to achieve the desired tradeoff between memory usage, db queries, and response time. The initial default of 3 days means Flow will attempt to keep in memcache all data models requested in the last 3 days.
$wgFlowCacheVersion 4.7 A version string appended to cache keys. Bump this if cache format or logic changes. Flow can be a cross-wiki database accessed by wikis running different versions of the Flow code; WMF sometimes overrides this globally in wmf-config/CommonSettings.php
$wgFlowSearchServers array( 'localhost' ) ElasticSearch servers
$wgFlowSearchConnectionAttempts 1 // see $wgCirrusSearchConnectionAttempts Flow search config setting - akin to CirrusSearch

See CirrusSearch.php for documentation for these params, which have similar

variable names (s/FlowSearch/CirrusSearch/)

$wgFlowSearchBannedPlugins array() // see $wgCirrusSearchBannedPlugins Flow search config setting - akin to CirrusSearch

See CirrusSearch.php for documentation for these params, which have similar

variable names (s/FlowSearch/CirrusSearch/)

$wgFlowSearchOptimizeIndexForExperimentalHighlighter false // see $wgCirrusSearchOptimizeIndexForExperimentalHighlighter Flow search config setting - akin to CirrusSearch

See CirrusSearch.php for documentation for these params, which have similar

variable names (s/FlowSearch/CirrusSearch/)

$wgFlowSearchMaxShardsPerNode array() // see $wgCirrusSearchMaxShardsPerNode Flow search config setting - akin to CirrusSearch

See CirrusSearch.php for documentation for these params, which have similar

variable names (s/FlowSearch/CirrusSearch/)

$wgFlowSearchRefreshInterval 1 // see $wgCirrusSearchRefreshInterval Flow search config setting - akin to CirrusSearch

See CirrusSearch.php for documentation for these params, which have similar

variable names (s/FlowSearch/CirrusSearch/)

$wgFlowSearchMaintenanceTimeout 3600 // see $wgCirrusSearchMaintenanceTimeout Flow search config setting - akin to CirrusSearch

See CirrusSearch.php for documentation for these params, which have similar

variable names (s/FlowSearch/CirrusSearch/)

$wgFlowSearchReplicas '0-2' // see $wgCirrusSearchReplicas Flow search config setting - akin to CirrusSearch

See CirrusSearch.php for documentation for these params, which have similar

variable names (s/FlowSearch/CirrusSearch/)

$wgFlowSearchShardCount array( 'flow' => 4 ) // see $wgCirrusSearchShardCount Flow search config setting - akin to CirrusSearch

See CirrusSearch.php for documentation for these params, which have similar

variable names (s/FlowSearch/CirrusSearch/)

$wgFlowSearchCacheWarmers array() // see $wgCirrusSearchCacheWarmers Flow search config setting - akin to CirrusSearch

See CirrusSearch.php for documentation for these params, which have similar

variable names (s/FlowSearch/CirrusSearch/)

$wgFlowSearchMergeSettings $wgFlowSearchMergeSettings = array(

'flow' => array( 'max_merge_at_once' => 10, 'segments_per_tier' => 10, 'reclaim_deletes_weight' => 2.0, 'max_merged_segment' => '5g', ), ); // see $wgCirrusSearchMergeSettings

Flow search config setting - akin to CirrusSearch

See CirrusSearch.php for documentation for these params, which have similar

variable names (s/FlowSearch/CirrusSearch/)

$wgFlowSearchIndexAllocation $wgFlowSearchIndexAllocation = array(

'include' => array(), 'exclude' => array(), 'require' => array(), ); // see $wgCirrusSearchIndexAllocation

Flow search config setting - akin to CirrusSearch

See CirrusSearch.php for documentation for these params, which have similar

variable names (s/FlowSearch/CirrusSearch/)

$wgFlowSearchEnabled false This allows running Flow without the search functionality. Right now, it's because the search functionality isn't ready for production, but we need to test it locally. We can decide later (after it's in production) whether to get rid of this setting. For example, this controls whether ApiFlowSearch is available.
$wgFlowAbuseFilterGroup 'flow' Custom group name for AbuseFilter

Acceptable values:

  • a specific value for flow-specific filters
  • 'default' to use core filters; make sure they are compatible with both core and Flow (e.g. Flow has no 'summary' variable to test on)
  • false to not use AbuseFilter
$wgFlowAbuseFilterEmergencyDisableThreshold 0.10 AbuseFilter emergency disable values for Flow
$wgFlowAbuseFilterEmergencyDisableCount 50 AbuseFilter emergency disable values for Flow
$wgFlowAbuseFilterEmergencyDisableAge 86400 // One day. AbuseFilter emergency disable values for Flow
$wgFlowAjaxTimeout 30 Timeout for Flow's AJAX requests (only affects ones that go through flow-api.js), in seconds
$wgFlowCoreActionWhitelist array( 'info', 'protect', 'unprotect', 'unwatch', 'watch', 'history', 'wikilove', 'move', 'delete' ); Actions that must pass through to MediaWiki on Flow-enabled pages
$wgFlowServerCompileTemplates false When set to true Flow will compile templates into their intermediate forms on every run. When set to false Flow will use the versions already written to disk. Production should always have this set to false.
$wgFlowEventLogging false Enable/disable event logging

Architecture[edit | edit source]

See Flow/Architecture.

Spam[edit | edit source]

See Extension:Flow/Spam for more information on how to fight spam in Flow.

Moderation[edit | edit source]

See Extension:Flow/Moderation for more information on moderation in Flow.