View source for Extension:Graph/Plans/en

<languages />
{{Tracked|T334940}}
== Update April 2024 ==

Hello everyone – I’m [[User:MMiller (WMF)|Marshall Miller]]; I’m a Senior Director of Product at WMF working with the product managers and teams that focus on the user experience of reading and editing the wikis.  Thank you all for being part of this ongoing conversation and being patient during the frustrating outage of [[Extension:Graph|the Graph extension]].  I gave the last update about graphs [[Extension talk:Graph/Plans#Update: 22 December|here]] and [[listarchive:list/wikimedia-l@lists.wikimedia.org/message/CPYNFK3PDTP6YVLZU3SLOJOXYJMOQHM5/|on wikimedia-l]].  I have since talked to many volunteers about their experiences and needs with graphs, and gathered a group of staff members to propose a plan.  I am back with a proposed plan for your feedback and input.  I'm posting here on the project page instead of the talk page so that this update can be marked for translation to other languages.  There is a new header on the talk page for discussion.

=== Summary ===

In short, we at the Wikimedia Foundation propose moving forward with an approach that many community members have suggested: '''building a new service to replace the Graph extension'''. This approach will enable editors to create basic visualizations, will require coordination with communities around migrating existing graphs, and will be extensible by developers who want to build and maintain additional functionality.

We’ve needed some time to consider all of the architectural questions and how to resource this work, and now we want to hear from volunteers on whether this sounds like the right approach. This work will be led by [[User:CCiufo-WMF|Chris Ciufo]], the product manager with the Design System team.  You can expect to hear from him going forward.  There’s more information below for those who want to see the details and considerations for this approach.

Since this work hasn’t started yet, there are still several months to go before the new graphs are operational.  We’ll be getting the right engineers involved and start architecting over the coming weeks, making sure we have a strong plan and are ready to iterate on it, and then likely starting this work in July as staff members become available from their previous projects.  We do not know yet how long it will take before the first types of graphs are operational.  We’re happy to discuss ideas that community members have about what, if anything, to do about the graphs continuing to be unavailable during these upcoming months.

=== Rationale ===

Chris and I are proposing this approach based on looking at how people have used graphs in the past, how we think they will use them in the future, and considerations on making sure our technology will be secure, scalable, and maintainable going forward.

In looking at how people have used graphs in the past, we see that graphs are a valuable, but not overwhelmingly common tool in the wikis. In English Wikipedia, graphs are used on about 10,000 articles, which is 0.15% of all articles, and across all Wikipedias, they are used on about 178,000, which is 0.28% of all articles.  Outside the main namespace, graphs are used more often, frequently because they are a part of templates that are displayed heavily.  For instance, in Arabic Wikipedia, there was a pageviews graph on every Article Talk page (until they were recently removed).  Importantly, we’ve noticed that the large majority of graphs are relatively simple: bar, line, pie, etc, and use data inline in the wikitext or in the Data namespace on Commons.  The resourcing for graphs should match this moderate usage – sufficient support, but not for complex functionality that isn’t widely used.

=== Technical discussion ===

The functionality of the new extension would be more limited compared to the old one, especially in that it won’t support all the visualization types and data sources of the old extension, but this approach represents a fresh start to a more sustainable future with graphs.

In terms of security, scalability, and maintainability, we decided in December that there was not a viable way to fix and continue with the legacy Graph extension.  Among other options, we [[phab:T165118|attempted upgrading to Vega 5]] (only to continue to find the same security issues), and we tried [[phab:T222807|wrapping the Vega canvas in a sandboxed iframe]] (which caused significant performance issues).  This meant that a path forward for graphs would require a new extension.

Here is the brief outline of the approach we’re thinking about:

* The legacy Graph extension would be sunset.
* The Foundation would build a new parser tag extension that supports a limited set of predetermined visualization types, like basic charts and maps, that cover the majority of existing use cases, which editors would specify in wikitext and get displayed as static images on wiki pages.
* Rendering server-side would avoid known or substantial security risks, such as those in the legacy Graphs extension.
* We do not know yet which visualization library or libraries it would use, whether [[:en:Vega_and_Vega-Lite_visualisation_grammars|Vega]], [[:en:D3.js|d3]] (which powers Vega), something like [https://ourworldindata.org/owid-grapher Our World in Data-Grapher], or something else.
* The new extension would support graph definition data specified inline or through Commons tabular data (in the Data: namespace), as was supported by the Graph extension. We would try to offer assistance to migrate legacy graphs using these data sources.
* It would be able to be extended with new visualization types by staff or volunteer developers through a controlled, centralized, and code-reviewable process.
* It would be able to be extended to draw data from other sources, such as Wikidata, which it won’t be built to do at the outset.
* It would display graphs on the Wikipedia iOS and Android apps (this was not possible with the Graph extension after Graphoid was decommissioned).
* It would be officially maintained by WMF to address bugs.

In the many conversations around graphs, volunteers have also raised longer term questions about “interactive content”, such as timelines and 3D objects. Rebuilding the capability to serve simple graphs securely will be a large amount of work for staff and volunteers. As part of this, the new extension will be readily extensible by volunteers who have the technical skill to add more sophisticated visualizations and more data sources. This may be an open door to some kinds of interactive content, but the larger topic of interactive content is worthy of separate, continued conversations moving forward.

=== Moving forward ===

Moving forward, we want to hear your thoughts on this approach:

* Does this seem like the right way to proceed?
* What are the basic visualization types that are most important to support? Which ones can we do without?
* Which use cases are you concerned about being missed?
* How will communities need to participate or react to these changes?

As we discuss, there are many important questions to sort through. One that is top of mind for me is what will happen with the ecosystem of templates and data sources that has been built around the Graph extension over the last ten years. While we want to make it easy for many of the existing graph specifications to work in the new system, we will need to think through this together.

Thank you for reading this long update and for continuing to be part of this effort. I know many of you have spent a lot of time over the past months discussing graphs and building workarounds. We’re looking forward to continuing the work.

: [[Extension talk:Graph/Plans#Update April 2024 (discussion)|Discussion for this update]]
== Historical details - To be updated soon ==

This page is a place for WMF staff and volunteers to gather the information needed for the WMF to decide the role it will play in ensuring the needs the {{ll|Extension:Graph|Graph}} extension emerged to serve continue being met.

== Progress ==
{| class="wikitable plainrowheaders"
|+Phases to fix Extension:Graph
!scope="col" |Phase
!scope="col" |Tracking task
!scope="col" |Status
!scope="col" |Completion date
|-
!scope="row"|[[Extension:Graph/Plans#📍 Phase 0: Invite volunteers to review roadmap|Phase 0: Invite volunteers to review roadmap]]
|
|{{Done}}
|{{Done}}
|-
!scope="row"|[[Extension:Graph/Plans#Phase 1: Validate Security of Sandboxing Approach|Phase 1: Validate Security of Sandboxing Approach]]
|Initial approach: [[phab:T222807|T222807]]
|Initial approach did not work.<ref>[[phab:T222807#9595905]], "Per [[phab:T334940#9537862|T334940#9537862]], not happening." –[[User:Tgr|Tgr]]</ref>
|
|-
!scope="row"|[[Extension:Graph/Plans#Phase 2a: Transition Graph Extension to Vega 5|Phase 2: Transition Graph Extension to Vega 5]]
|[[phab:T165118|T165118]]
|{{In progress}}
|
|-
!scope="row"|[[Extension:Graph/Plans#Phase 3: Define maintenance responsibilities and security/incident response|Phase 3: Define maintenance responsibilities and security/incident response]]
|
|
|
|-
!scope="row"|[[Extension:Graph/Plans#Phase 4: Deploy Graph Extension (Vega 2 + 5) in a Sandboxed iFrame with a restrictive content security policy to production|Phase 4: Deploy Graph Extension (Vega 5)]] 
|
|
|
|-
!scope="row"|[[Extension:Graph/Plans#Phase 5: Optimize the Graph Extension's longevity|Phase 5: Optimize the Graph Extension's longevity]]
|
|
|
|}


== Roadmap ==

=== 📍 Phase 0: Invite volunteers to review roadmap ===

''Objective''

Ensure volunteers understand and are sufficiently supportive of Phases 1-5 so that we (staff and volunteers) can efficiently make decisions/tradeoffs as they emerge through implementation. 

''Steps''

# '''Volunteers''' and '''WMF''' to discuss [[#Roadmap|the proposed roadmap]] and improve it as needed.

=== Phase 1: Validate Security of Sandboxing Approach ===

''Objective''

Ensure the sandboxed iFrame is sufficiently secure by '''1)''' implementing the Graph Extension using Vega 5 on the [[wikitech:Nova_Resource:Deployment-prep|Beta Cluster]] and '''2)''' publishing the documentation and tooling necessary for volunteers and staff to assess its security.

''Steps''

# Complete [[phab:T222807#9087509|work in progress sandboxing patch]] to provide the basic infrastructure for future steps.
# Create a “test box” page, either as an extension or a Special page in core, which allows execution of arbitrary JavaScript inside the infrastructure sandbox.
# Deploy the “test box” page on the [[wikitech:Nova_Resource:Deployment-prep|Beta Cluster]], with appropriate initial sandbox rules.
# Pen test the "test box" page to assess its security and refine the sandbox rules iteratively.
# Perform any relevant static security analysis against updated code prior to deployment.

=== Phase 2: Transition Graph Extension to Vega 5 ===

''Objective''

Ready the Graph Extension for Vega 5 by re-implementing Vega 2 features using the Vega 5-compatible syntax so that, going forward, all new graphs will benefit from Vega 5's security, accessibility, and syntax improvements.

''Steps''

# Connect Vega 5 to the sandbox infrastructure; implement additional sandbox checks to the Vega 5 loader as necessary.
# (Re)implement protocol support for Vega 5, based on the Vega 2 implementations while assessing them for security and maintainability.
# Deploy Vega 5-in-a-sandbox to the [[wikitech:Nova_Resource:Deployment-prep|Beta Cluster]] to allow volunteers to perform initial evaluations.
# Test and evaluate "Vega 5-in-a-sandbox" approach.
# Conduct additional security testing with Vega5-specific payloads to follow up on the work in Phase 1.
# Convert the existing Vega 2-to-5 converter to a “2-to-5 tool”, which helps volunteers convert existing Vega 2 specifications to Vega 5 syntax.
# Implement a message similar to what [[User:Pietrasagh|Pietrasagh]] described<ref>[[Extension talk:Graph/Plans#c-Pietrasagh-20230917162800-PPelberg (WMF)-20230915235200]]</ref> that prompts people to migrate Vega 2-based graphs to Vega 5. 

=== Phase 3: Define maintenance responsibilities and security/incident response ===

''Objective''

Define '''what''' level of maintenance support volunteers can expect, '''who''' will be responsible for providing that support, and '''how''' we will respond to security/incident response going forward so that staff can feel confident deploying the extension and volunteers can feel confident depending on it.

''Steps''
# Determine who within WMF will be responsible for security/incident response going forward.
# Define a maintenance and support plan that sets clear expectations about what volunteers can expect from WMF as it relates to the Graph Extension going forward and what team(s) will be responsible for delivering that support. ''E.g. upgrading to future versions of Vega and other tasks listed in Phase 5.''

=== Phase 4: Deploy Graph Extension (Vega 5) in a Sandboxed iFrame with a restrictive content security policy to production ===

''Objectives''

Offer volunteers access to the information and capabilities disabling the Graph Extension has left them without.

Develop the resources (documentation + tooling) necessary to support volunteer porting efforts

''Steps''

# In collaboration with volunteers, create “Vega 5 porting” page linking both to the upstream 2-to-5 porting documentation as well as specific information relative to Extension:Graph. E.g. changes to protocols, wiki best practices, related templates and modules, etc.
## ''If appropriate, documentation can also mention how to access the “last Vega 2” version of the graph-to-be-ported from archive.org.'' 
# With community, port existing Lua modules which generate Vega 2 output to emit Vega 5 output instead.
# Port existing Vega 2 graphs to Vega 5 and offer tools that help ease this transition
# Build a more robust catalog of use cases and what Vega features can be relied on

=== Phase 5: Optimize the Graph Extension's longevity ===

''Objective''

Optimize the Graph Extension's longevity and support the community building graphs on Wikimedia projects.

''Steps''
# Deprecate, and then remove support for Vega 2 from the codebase, creating categories or linter tags to mark any remaining Vega 2 graphs.
# Formally transfer Graph Extension maintenance responsibilities to a Wikimedia Foundation engineering team.
# Create tools and document processes to facilitate routine updates to Vega from upstream for minor/patch/security releases and commit to an appropriate SLA.

== FAQ ==
# '''When can we expect to see a timeline for [[Extension:Graph/Plans#Roadmap|the Roadmap above]]?''' 
## The team expects there to be a timeline to share during the first or second week of November 2023. By this time, we think we will know whether volunteers see any fundamental issues with [[Extension:Graph/Plans#Roadmap|the roadmap]] that warrant it being revised.
# '''Once re-enabled, will the Graph Extension support pseudo-protocols?''' Yes. Once the Graph Extension is re-enabled, it ''will'' support the protocols already implemented in [[phab:T335325|T335325]].  Of course, if there are particular ones you think ought to be supported, we'd value you naming them and sharing why [[Extension talk:Graph/Plans|on the talk page]], as [[User:Snævar|Snævar]], [[User:Bawolff|Bawolff]], [[User:Nikki|Nikki]], and [[User:Pietrasagh|Pietrasagh]] have started doing.<ref>[[Extension talk:Graph/Plans#c-Snævar-20230916095400-PPelberg (WMF)-20230915235200]]</ref><ref>[[Extension talk:Graph/Plans#c-Bawolff-20230916100200-Snævar-20230916095400]]</ref><ref>[[Extension talk:Graph/Plans#c-Nikki-20230919115700-Snævar-20230916095400]]</ref><ref>[[Extension talk:Graph/Plans#c-Pietrasagh-20230917162800-PPelberg (WMF)-20230915235200]]</ref> ''Please note: protocol support is a notably fragile part of the Graph Extension. If/when we come to learn this facet of the extension is causing problems, we might need to disable protocol support.''
# '''How much time – if any – will elapse between the Graph Extension being re-enabled with support for Vega 5 and support for Vega 2 being discontinued?'''<ref>Thank you, [[User:Nux]] for [[Extension talk:Graph/Plans#c-Nux-20230916125800-Why not just start with v5?|entering the idea]] that prompted this question.</ref>  In short, we do not yet know when support for Vega 2 will be discontinued. This is a timeline we (staff + volunteers) will need to define together.  With the above said, here is what we are certain about at it relates to Vega 2 and Vega 5 support:
## Being able to provide guidance about when Vega 2 support will be discontinued depends on us first learning how the migration to Vega 5 is going.<ref>Where "learning how the migration to Vega 5 is going" in this context could mean answering questions like: ''"Of all the graphs generated using the Graph Extension, what percentage of them are using Vega 2 and Vega 5?" "How is the rate at which volunteers are migrating from Vega 2 to Vega 5 evolving over time?"''</ref>
## We do not plan to support Vega 2 graphs indefinitely
# '''What can we do to preserve graphs that have not/can not be converted from Vega 2 to Vega 5?'''  Converting graphs of this sort on a server that allows sandboxed rendering exposes security vulnerabilities the current approach is meant to mitigate. ''More details in [[phab:T334940#9161842|T334940#9161842]].''   With the above said, we estimate the graphs that have not/cannot be ported from Vega 2 to Vega 5 to be relatively small and comprised of:
## Graphs that use a custom protocol (e.g. Wikimedia API or WDQS) the sandboxed iFrame approach does not support.
## Graphs that can be ported, but no one has undertaken the work to do so.
#'''Why do we think it's worthwhile to migrate from Vega 2 to Vega 5?'''{{Anchor|Vega 2 → Vega 5 transition}}
##Vega 2 has been superseded by Vega 3, 4, then 5 upstream.  Upstream and third-party documentation exclusively refers to syntax in “Vega version 3.0 and later”, and it is difficult for new contributors to find documentation relevant to Vega 2.  The last upstream release (bugfix or security) of Vega 2.x was in January 2017.  Vega 5 was released in March 2019 and is still under active maintenance and development, with the latest 5.25.0 release in April 2023.
##Volunteers have reported issues with Vega 2's accessibility, syntax, and overall functionality, per [[m:Community Wishlist Survey 2023/Multimedia and Commons/Update Vega to the latest build|this 2023 wish]].
##Vega 5 has made improvements to the library's expression layer that harden it from a security perspective compared to Vega 2.  It is not perfect, but by introducing a parsed expression grammar it offers a more robust foundation for additional security hardening in the future if it proves necessary.
##Maintaining multiple versions of Vega concurrently is unsustainable in the long run. The wiki community is taxed in the attempt to independently support software which is not being maintained upstream. Our efforts are best spent working in cooperation with upstream and third-party developers, and to do this we need to be working from the upstream Vega 5 code base.
#'''What might be required to migrate graphs from Vega 2 to Vega 5?'''
##Create a converter that would migrate Vega 2-based graphs to be compatible with Vega 5. @[[User:Jdlrobson|Jdlrobson]] started work on an initial approach in [[phab:T335048#8794138|T335048#8794138]].  The initial work needs to be restructured slightly to refocus it on being an aid to manual porting, instead of the automatic translator which was its original goal.   ''Note: We estimate this converter currently works for ~80% of graphs, with diminishing returns on additional engineering effort to cover more.  We do not plan on continuing to invest significant additional engineering resources here, but instead to simply repurpose the existing codebase as an aid to manual porting.''
##Volunteers would need to update <bdi lang="zxx" dir="ltr"><code><nowiki><graph></nowiki></code></bdi> syntax on a case-by-case basis, aided by (1) the ability to run the existing Vega 2 and new Vega 5 specification side-by-side, (2) the partial Vega2-to-5 porting tool which handles 80% of the “obvious” keyword changes and other mechanical conversions, (3) [https://vega.github.io/vega/docs/porting-guide/ the upstream Vega2 porting guide], and (4) additional documentation or tools which might be created by the wiki community.
##Update the limited number of Scribunto templates on-wiki which generate <bdi lang="zxx" dir="ltr"><code><nowiki><graph></nowiki></code></bdi> output in Vega 2 format to instead output Vega 5.  This requires both lua and Vega expertise, but fixes a larger number of Vega 2 uses on wiki at once.

== Proposal ==

To safely restore access to the information and capabilities disabling the Graph Extension has left people without and promote the volunteer+staff collaboration needed to do so, '''we (the WMF) are committing to''':

Re-enable the Graph Extension in a sandboxed iFrame with a [[:en:Content_Security_Policy|restrictive content security policy]].

# Once the Graph Extension is reenabled, it will continue to work with Vega 2 for a yet-to-be defined period of time. ''Note: we'll need to define this window together.''
## After that "yet-to-be defined period of time," Vega 2 support will be discontinued and use of the Graph Extension will require volunteers to make graphs with Vega 5.
## As soon as possible, make the sandboxed Graph extension available on the beta cluster for testing. ''See: [[phab:T346292|T346292]].''
# Investigate the viability of adding logging to increase our awareness of instances where people are exploiting the security vulnerabilities inherent with restoring support for Vega on our platform. ''See [[phab:T346414|T346414]].''
# Publish the technical documentation needed for developers across the Movement to ''understand'' how we implemented the sandboxed CSP approach
# Publish a clear timeline for when you all can expect all of the above to happen  
# ''Note: exploratory work to redeploy the Graph Extension in a sandboxed iframe has started. See [[phab:T222807|T222807]].''
# Share regular updates about the progress we're making on the commitments named above on Phabricator and MediaWiki.
# Support volunteers with code and processes that will ease the transition from Vega 2 to Vega 5 when the time for this transition comes.

In support of the above, we'd need to '''depend on ya'll (volunteers)''' to:

# Spread awareness of this proposal and the updates that will come as we start implementation, assuming this proposal moves forward.
# Manually migrate some proportion of Vega 2-based graphs to be compatible with Vega 5. ''See the "[[#Vega 2 → Vega 5 transition|questions 5 and 6 in the FAQ section]]".''
# ''Potentially'', fix/port graphs that attempted to fetch live data using methods that the sandboxing approach inhibits.
## ''Note: the need for the above will become clear once we decide on whether we will restore the pseudo-protocols that were used to fetch data live from the action API, the REST API, WDQS etc, and the precise sandbox parameters we select (domains/ports/http methods allowed). This decision will be made in [[phab:T346291|T346291]].''
:
== Research ==

The research that informed the {{ll|Extension:Graph/Plans#Proposal|the proposal}} for safely and securely restoring access to the information and capabilities {{ll|Extension:Graph/Plans#Background|disabling the Graph Extension}} has left people without {{ll|Extension:Graph/Plans/Research|can be found here}}.

== References ==
<references />

[[Category:Extension:Graph{{#translation:}}]]