[RFC] Compatibility layer

[Qix-]

One problem we're going to be facing, now that I'm thinking about it:

We will be introducing the ability to specify a custom output format with #582.

This new output support (the env-var support) won't be available for older versions, which means debug will now be showing different output formats for old versions of the library, which is a problem since debug is almost as old as node.js IIRC.

That means users that set DEBUG_FORMAT will see inconsistent output formats for code that is any older than the new major version release.

---

Should there be a compatibility layer introduced in the newest version that sniffs out older versions of debug and patches them up, being version-aware in terms of the API?

[chagris]

I'm not sure I understand -- I thought the goal of #582 was to introduce a minor version with a default format that'd be backward-compatible with older versions (identical format, show / hide date and color if output is a tty, support env vars like DEBUG_HIDE_DATE and DEBUG_COLOR), then make a major version bump that'd drop support for those, as written there #582 (comment)

Did I miss something? What would a "compatibility layer" have to patch, and if the newest version is installed, doesn't that means there would be no older version to patch?
(sorry if those are stupid questions!)

[Qix-]

The old versions will still have the old version (versions 0.x, 1.x, 2.x and 3.x). Either we back-port or we monkeypatch, really.

So the problem is that old libraries that have a range of e.g. ^1 or <3 or pin a specific version will have those versions installed separately, meaning there will be multiple versions of debug being imported together.

Luckily, it looks like the environment variables and general API have remained pretty much the same since 0.x, which means patching is not a bad route to go.

The problem with backporting is that it runs the risk of breaking a lot of people.

To be clear, the problem is this: versions 0.x, 1.x, 2.x and 3.x would not know to look for the DEBUG_FORMAT variable. So if someone has set it to something different, only libraries that use the newest version will see the change in output, which means there runs the risk of having many different debug formats being logged out and confusing the heck out of everyone.

[Qix-]

Since the patching or backporting is really risky, perhaps there's a third way by using node -r. People that cared for seeing a consistent format would install a compatibility module that worked alongside debug and could run node -r to use it.

There are a few problems with this approach:

• It's unclear how to use it in the browser (it'd have to be bundled in to work, and it'd have to be adapted (somehow) for all bundlers)
• It'd probably never go away. Too many super old modules depend on super old versions of debug, and they will most likely never upgrade. It would turn into a bit of a nightmare of always having to node -r <some-compat-module>.
• Not having something automatic means potentially breaking users that have depended on the specific output of debug. It's definitely not a good practice to be doing it, but the fact is someone out there (e.g. perhaps Sentry) has written a parser for debug lines that would likely break.

It's a rock and a hard place, really.

I do like the idea of making debug more like SLF4J, where the user could write logging handlers and load them in using node -r, but that's a large departure from the current state and I would imagine that would upset a lot of people.

---

@TooTallNate @sindresorhus your thoughts would be really appreciated here. Any ideas on the best way to tackle this problem?

[sindresorhus]

I don't think it's feasible to backport to all old versions. Some packages might even have the dependency locked to a specific debug version too, so it would not work then. And if you can't reliably do for all situations, is there really any point.

This would be a good time to come up with some way to monkeypatch that would let you introduce other flags and changes in the future too. Maybe by making all the debug() instances minimal with a well defined transport that will never change and have the core as a singleton that mediates those minimal instances, where it uses the newest registered core. Since the latest version always becomes the singleton, it knows how to handle all older versions.

[Qix-]

Well if we monkey patch then maybe we can funnel into a log handler, which can then be plugged into optionally by node -r. Then we could have a json log consumer and not have to deal with those formatters (cc @chagris).

Best of both worlds.

[Qix-]

Something else to consider: #425 - .enable() and .disable() being renovated for 5.x release is going to be a weird issue to solve at the compatibility layer.

Just want to make sure it's on the radar.

[Qix-]

In terms of node -r see #556.

[smahmood0]

You guys are right