Rename the generic `DEBUG` environment variable to a project-specific one

[PierreRaybaut]

Summary

DataLab — and other libraries of the same stack (guidata, Sigima) — currently activates its debug mode when the bare DEBUG environment variable is set to 1 / true:

• datalab/config.py

  DEBUG = os.environ.get("DEBUG", "").lower() in ("1", "true")
  if DEBUG:
      print("*** DEBUG mode *** [Reset configuration file, do not redirect std I/O]")

• datalab/env.py

  DEBUG = os.environ.get("DEBUG", "").lower() in ("1", "true")

DEBUG is far too generic an environment-variable name. It collides with widely-used third-party conventions (Django, Flask, Node.js tooling, many CI systems, ad-hoc shell exports, IDE run configurations, …). A user who has DEBUG=1 exported in their shell or CI for an unrelated reason will silently trigger DataLab's debug paths.

The most concerning consequence is that, in datalab/config.py, DEBUG controls whether the user configuration is reloaded:

Conf.initialize(config_app_name, CONF_VERSION, load=not DEBUG)

i.e. when DEBUG is true, DataLab resets the user configuration file at startup. A globally-exported DEBUG=1 therefore quietly wipes user preferences with no opt-in from the user.

Proposal

Rename the environment variable from DEBUG to DATALAB_DEBUG, with no backward-compatibility shim. The bare DEBUG variable is the bug — keeping a fallback (even with a DeprecationWarning) would preserve the very data-loss footgun this issue exists to remove. A clean rename is also simpler to implement, document and reason about.

The namespaced convention is already established in the stack:

• guidata already exposes GUIDATA_PARSE_ARGS.
• sigima/viz/viz_plotpy.py already reads SIGIMA_DEBUG.

So the rename merely makes the existing convention consistent.

Suggested implementation

In datalab/env.py and datalab/config.py, replace:

DEBUG = os.environ.get("DEBUG", "").lower() in ("1", "true")

with:

DEBUG = os.environ.get("DATALAB_DEBUG", "").lower() in ("1", "true")

The Python-level DEBUG constant name is intentionally kept so that all existing if DEBUG: call sites (datalab/widgets/status.py, datalab/config.py, datalab/env.py, …) remain untouched.

Acceptance criteria

• DATALAB_DEBUG=1 enables debug mode (banner printed, config reset skipped exactly as before).
• Bare DEBUG=1 has no effect on DataLab.
• Release-note entry under doc/release_notes/release_X.YY.md flagged as a breaking change for the (developer-only) debug env var.
• CONTRIBUTING.md and any documentation page that mentions DEBUG=1 updated to use DATALAB_DEBUG=1.

Verification

• Run DataLab with DATALAB_DEBUG=1 and confirm the *** DEBUG mode *** banner appears and the config file is not reloaded.
• Run DataLab with bare DEBUG=1 and confirm normal startup (no banner, no config reset).
• Existing pytest suite must stay green.

Related work in sibling projects

The same rename should be applied to the libraries of the stack that read a bare DEBUG env var. Each repository will track its own issue, but this ticket lists them for cross-reference:

Project	File	New variable
guidata	guidata/env.py (line 20)	GUIDATA_DEBUG
Sigima	sigima/tests/env.py (line 33)	SIGIMA_DEBUG
DataLab	datalab/config.py, datalab/env.py	DATALAB_DEBUG

The following stack projects do not read a bare DEBUG env var and are therefore out of scope: PlotPy, PythonQwt, DataLab-Kernel, DataLab-Web.