From 3363f181e7968fe58ed5a6acee94521043e21d55 Mon Sep 17 00:00:00 2001 From: marco-ippolito Date: Wed, 17 Jan 2024 19:50:11 +0100 Subject: [PATCH] doc: document console changes as breaking --- doc/contributing/collaborator-guide.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/doc/contributing/collaborator-guide.md b/doc/contributing/collaborator-guide.md index a7021db9b2af48..14db28420dcc3e 100644 --- a/doc/contributing/collaborator-guide.md +++ b/doc/contributing/collaborator-guide.md @@ -19,6 +19,7 @@ * [Breaking changes](#breaking-changes) * [Breaking changes and deprecations](#breaking-changes-and-deprecations) * [Breaking changes to internal elements](#breaking-changes-to-internal-elements) + * [Breaking changes to console APIs](#breaking-changes-to-console-apis) * [Unintended breaking changes](#unintended-breaking-changes) * [Reverting commits](#reverting-commits) * [Introducing new modules](#introducing-new-modules) @@ -354,6 +355,7 @@ Examples of breaking changes include: * Adding or removing errors. * Altering expected timing of an event. * Changing the side effects of using a particular API. +* Changing the output of some [console APIs](#breaking-changes-to-console-apis). #### Breaking changes and deprecations @@ -378,6 +380,20 @@ an effort to determine the potential impact of the change in the ecosystem. Use If a change will cause ecosystem breakage, then it is semver-major. Consider providing a Public API in such cases. +### Breaking changes to console APIs + +Console APIs are a debugging tool, and the format of their output should generally not +considered stable. +However due to the nature of the Node.js ecosystem, users rely on stability of +the output of some of these APIs for snapshot testing, parsers, etc... +To avoid breaking changes, some behaviors should be considered stable. +The following changes in the output are to be considered breaking changes: + +* `console.table` (padding, alignment, etc...). +* changing the color of all console methods. +* changing the signature of all console methods. +* changing the output for single string inputs. + #### Unintended breaking changes Sometimes, a change intended to be non-breaking turns out to be a breaking