plotly / plotly/plotly.js

[FEATURE]: Improve contributor documentation for WebGL rendering and debugging workflow

Open
#7,772 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation feature P3 size: 1
Dominant language
JavaScript
Stars
18.3k
Forks
2k
Avg merge
2d 12h
Merged PRs (30d)
28

Description

Problem

While contributing a fix for issue #7387, I found that understanding the WebGL rendering flow (especially for scattergl) required significant exploration of the codebase.

There is currently limited contributor-oriented documentation explaining:

  • how WebGL traces are structured
  • where rendering logic is implemented
  • how functions like regl.clear() are expected to behave
  • how to debug rendering-related warnings

Proposed Solution

Add a short developer-focused documentation section covering:

  • Overview of WebGL-based traces (e.g., scattergl)
  • Key rendering pipeline entry points
  • Usage patterns for regl.clear() and buffer management
  • Common debugging scenarios and tips

Possible Implementation

This could be added as:

  • a section in CONTRIBUTING.md
  • a new markdown file (e.g., docs/webgl_debugging.md)
  • or a developer note linked from the main documentation

Benefits
  • Helps new contributors onboard faster
  • Reduces debugging time
  • Improves code maintainability
  • Encourages more contributions in rendering-related areas

Context

This suggestion is based on my experience contributing to:
https://github.com/plotly/plotly.js/issues/7387

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with CONTRIBUTING.md and the possible docs/webgl_debugging.md location, then use issue #7387 and the scattergl rendering flow as context. Document WebGL trace structure, rendering entry points, regl.clear() and buffer-management patterns, plus debugging tips for rendering warnings; done means contributors can follow the workflow without extensive codebase exploration.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
computer-graphics, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.