Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: document console changes as breaking #51503

Closed
wants to merge 2 commits into from
Closed

doc: document console changes as breaking #51503

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3363f18
doc: document console changes as breaking
marco-ippolito Jan 17, 2024
181f49a
Update doc/contributing/collaborator-guide.md
marco-ippolito Jul 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions doc/contributing/collaborator-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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

Expand All @@ -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
be 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like this is less about the color (visual appearance when connected to a TTY) and more about the contract of outputting raw strings unmodified to the output stream when piped (without adding additional control sequences).

The visual color of the output can change easily as util.inspect() is evolved and doesn't matter for interactive use, but a lot of users rely on console.error(str) or console.log(str) to output str untouched to process.stderr/process.stdout, e.g. for logging JSON in production.

Copy link

@unphased unphased Oct 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to be fair process.stdout/stderr .write() has always been available to use for these needs and additionally gives control over whether a newline is inserted. The pain is around correcting all the code that needs this changed. One might argue it to be superior to make a NEW set of console or other APIs that could gain features like this and maybe steadily enhance those features over time.

I have to assume that this was the whole point of the console interface from the beginning... After all, it has slick stuff like console.table() that everyone knows not to rely on its implementation specific properties.

I am just as guilty myself for opting to use console.error instead of process.stderr.write. This situation seems unavoidable

* changing the signature of all console methods.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The signature is as-stable as every other API call and the rest aren't stable (are they?)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I dont know if the signature is considered stable but not the output, if its obvious Im gonna remove it

* changing the output for single string inputs.

#### Unintended breaking changes

Sometimes, a change intended to be non-breaking turns out to be a breaking
Expand Down