plotly / plotly/plotly.js

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

Ouverte
#7,772 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

documentation feature P3 size: 1
Langage dominant
JavaScript
Étoiles
18.3k
Forks
2k
Merge moyen
2 j 12 h
PR mergées (30 j)
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

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Commencez par CONTRIBUTING.md et l’emplacement possible docs/webgl_debugging.md, puis utilisez l’issue #7387 et le flux de rendu de scattergl comme contexte. Documentez la structure des traces WebGL, les points d’entrée du rendu, regl.clear() et les modèles de gestion des buffers, ainsi que des conseils de débogage pour les avertissements de rendu ; le travail sera considéré comme terminé lorsque les contributeurs pourront suivre le workflow sans explorer largement la base de code.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
javascript
Domaine
computer-graphics, documentation
Type d'issue
Documentation
Difficulté
3/5
Temps estimé
1-2 jours
Activité
Calme
Clarté
Plutôt claire
Accessibilité débutants
48/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.