feat: add streams guide #7123

Ceres6 · 2024-10-16T08:25:21Z

Description

This PR adds a stream guide for the learn section

Validation

Lint passing and checked visually

Related Issues

Closes nodejs/node#8646

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run npm run format to ensure the code follows the style guide.
I have run npm run test to check if all tests are passing.
I have run npx turbo build to check if the website builds without errors.
I've covered new added functionality with unit tests if necessary.

Co-authored-by: Matteo Collina <[email protected]>

vercel · 2024-10-16T08:25:26Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
nodejs-org	✅ Ready (Inspect)	Visit Preview	Nov 17, 2024 11:15am

Ceres6 · 2024-10-16T08:42:45Z

I'm missing translation for the titles as I didn't want to use translator ones

package.json

AugustinMauroy · 2024-10-16T10:09:44Z

I'm missing translation for the titles as I didn't want to use translator ones

You mustn't touch to translation fille it's handle with crowdin

Ceres6 · 2024-10-16T13:16:48Z

I'm missing translation for the titles as I didn't want to use translator ones

You mustn't touch to translation fille it's handle with crowdin

So should I remove the en.json change?

AugustinMauroy · 2024-10-16T19:26:26Z

I'm missing translation for the titles as I didn't want to use translator ones

You mustn't touch to translation fille it's handle with crowdin

So should I remove the en.json change?

I mean you just have to update en.json and don't touch to translated file

Ceres6 · 2024-10-21T10:33:01Z

cc @mcollina @Trott

mcollina · 2024-10-21T11:09:37Z

Can you please add a sentence at the beginning or end saying that this guide is a derivative of https://blog.platformatic.dev/a-guide-to-reading-and-writing-nodejs-streams?

simoneb · 2024-10-22T12:48:01Z

@mcollina do we want any corporate references to material that lands on the Node.js website? Asking because, in a similar vein, the article was reviewed by multiple people at Nearform, including myself, and we weren't going to ask @Ceres6 to attribute us.

On the other hand, we were considering to publish the very same article on our company's blog, with a reference to the official documentation, as the authoring has in practice being supported by us.

mcollina · 2024-10-25T15:20:59Z

@mcollina do we want any corporate references to material that lands on the Node.js website? Asking because, in a similar vein, the article was reviewed by multiple people at Nearform, including myself, and we weren't going to ask @Ceres6 to attribute us.

@simoneb You can see there are very few original contributions to what has been added here compared to what I wrote in the article, as multiple paragraphs were taken verbatim, including the whole of the introduction.

By all intents and purposes, I'm the primary author of this PR, and I gave permission to use my original piece if I was included as a co-author of it and kindly asked for a backlink if possible.

Adding a backlink is not unreasonable to ask. It's also ok if it's not added, but I would prefer it.

do we want any corporate references to material that lands on the Node.js website?

I think the question for the @nodejs/tsc is:

Should we add a backlink in case existing material is used in the Learn section of the website?

(We should not be using existing material without the author permission anyway).

mcollina · 2024-10-25T15:38:30Z

Here is a proposal, how about you include in the commit description:

a link of the original piece
a mention of all people at NearForm that reviewed it

So we keep a record of the origin of this content.

Ceres6 · 2024-10-25T15:46:28Z

@mcollina I'm happy to add the backlink. I'm guessing now the TSC is tagged we should wait until that gets discussed, right?

EDIT: I saw that some resources in the learn section have an authors frontmatter prop, maybe that's another option to consider?

mcollina · 2024-10-25T16:00:03Z

I think it's good if the TSC discuss this because I suspect it would come out more and more.

@Ceres6 you should definitely fill in the authors block in the frontmatter. It should appear something like:

Ceres6 · 2024-10-25T16:22:15Z

Cool! I'll add authors then and wait for the TSC discussion on the backlink. Just one doubt, should I add Nearform reviewers as authors or are those not considered as such? @mcollina

mcollina · 2024-10-25T16:30:56Z

I would list them all.

ovflowd · 2024-10-28T21:31:18Z

Hey folks 👋 are we happy here?

github-actions · 2024-10-28T21:32:58Z

Lighthouse Results

URL	Performance	Accessibility	Best Practices	SEO	Report
/en	🟠 87	🟢 100	🟢 100	🟢 91	🔗
/en/about	🟢 100	🟢 100	🟢 100	🟢 91	🔗
/en/about/previous-releases	🟢 99	🟢 100	🟢 100	🟢 92	🔗
/en/download	🟢 99	🟢 100	🟢 100	🟢 91	🔗
/en/blog	🟢 100	🟢 100	🟢 96	🟢 92	🔗

github-actions · 2024-10-28T21:34:18Z

Unit Test Coverage Report

Lines	Statements	Branches	Functions
	90.38% (592/655)	75.43% (172/228)	94.26% (115/122)

Unit Test Report

Tests	Skipped	Failures	Errors	Time
132	0 💤	0 ❌	0 🔥	5.166s ⏱️

ovflowd · 2024-11-16T13:42:07Z

apps/site/navigation.json

@@ -323,6 +323,10 @@
            "backpressuringInStreams": {
              "link": "/learn/modules/backpressuring-in-streams",
              "label": "components.navigation.learn.modules.links.backpressuringInStreams"
+            },
+            "howToUseStreams": {


This learn page should be before backpressure in streams IMO.

I'll change it, I thought they needed to be in order of creation, but it makes sense to have this first as it is more basic/general

ovflowd

Content-wise (first glance) it looks great. @nodejs/tsc I see this is still in the TSC agenda. Any blocker here?

avivkeller

Reads well, just some minor grammar adjustments, among other things.

apps/site/pages/en/learn/modules/how-to-use-streams.md

avivkeller · 2024-11-16T20:13:03Z

apps/site/pages/en/learn/modules/how-to-use-streams.md

+[`process.stdout`]: https://nodejs.org/api/process.html#processstdout
+[`process.stderr`]: https://nodejs.org/api/process.html#processstderr
+[Matteo Collina]: https://github.com/mcollina
+[Platformatic's Blog]: https://blog.platformatic.dev/a-guide-to-reading-and-writing-nodejs-streams


Some links are inline, while others are like this, can you make them all uniform?

The rule that should be applied is this. If the link is used once, we put it inline if it is used several times in the bottom

That's not what happening in this article. In this article, some are inline, some aren't. IMO one of the following should be done

All inline (preferably not)

All text-based references (I like this the best)

Inline unless used multiple times

I think (almost) all of them are used only once. I like the idea of having them all at the bottom as it's like a bibliography. I haven't seen anything documented about this rule, but I'm happy to go either way as long as we agree

IMO as you said, having them at the bottom is cleaner

I put them all at the end, hope that's okay

apps/site/pages/en/learn/modules/how-to-use-streams.md

avivkeller · 2024-11-17T01:41:28Z

Content-wise (first glance) it looks great. @nodejs/tsc I see this is still in the TSC agenda. Any blocker here?

According to the minutes from November 13th, they are still? deliberating on the policy of external content attribution.

Ceres6 · 2024-11-17T09:16:53Z

Content-wise (first glance) it looks great. @nodejs/tsc I see this is still in the TSC agenda. Any blocker here?

According to the minutes from November 13th, they are still? deliberating on the policy of external content attribution.

As far as I can see there were only opinions in favour of adding them, not sure if there should be a formal ruling or something

Co-authored-by: Aviv Keller <[email protected]> Signed-off-by: Carlos Espa <[email protected]>

avivkeller · 2024-11-17T21:49:36Z

It'll be discussed at every-ish meeting while it's on the agenda. Once they remove the label, they should come to a formal dicision.

(Also BTW this isn't the first time we've reposted external content with permission, see

nodejs.org/apps/site/pages/en/blog/module/multi-server-continuous-deployment-with-fleet.md

Line 9 in 83081ef

    
           _This is a guest post by James "SubStack" Halliday, originally posted [on his blog](http://substack.net/posts/16a9d8/multi-server-continuous-deployment-with-fleet), and reposted here with permission._

)

Ceres6 · 2024-11-26T21:31:24Z

@mcollina did you have time to review it?

styfle · 2024-12-05T14:35:32Z

apps/site/pages/en/learn/modules/how-to-use-streams.md

+class MyStream extends Readable {
+  #count = 0;
+  _read(size) {
+    this.push(':-)');


Why :-)? Could this be changed to something that helps the reader understand?

Also can we use size since this parameter is currently unused.

ovflowd · 2024-12-16T12:45:17Z

@mcollina did you have time to review it?

Bump, @mcollina

simoneb · 2024-12-18T10:21:36Z

Hey folks, this has been here for a couple of months, can we try to move it forward? It's just a guide to be added to the docs.

I believe we agreed that we're going to credit @mcollina and Platformatic explicitly in the content, and myself and @codyzu in the markdown metadata.

I'm happy with that, so unless anybody disagrees, I would suggest to move this forward.

ovflowd · 2024-12-18T23:33:34Z

Hey folks, this has been here for a couple of months here, can we try to move it forward? It's just a guide to be added to the docs.

I believe we agreed that we're going to credit @mcollina and Platformatic explicitly in the content, and myself and @codyzu in the markdown metadata.

I'm happy with that, so unless anybody disagrees, I would suggest to move this forward.

Hey there, we can only move forward with explicit approval from the TSC. Hence we gotta wait for @mcollina

mcollina

lgtm

mcollina · 2024-12-21T09:01:22Z

Sorry about the wait, I had a significant build-up of OSS work to crunch.

feat: add streams guide

55ff431

Co-authored-by: Matteo Collina <[email protected]>

Ceres6 requested a review from a team as a code owner October 16, 2024 08:25

vercel bot deployed to Preview October 16, 2024 08:27 View deployment

AugustinMauroy reviewed Oct 16, 2024

View reviewed changes

package.json Outdated Show resolved Hide resolved

mcollina added tsc-agenda blocked labels Oct 25, 2024

mcollina removed the blocked label Oct 25, 2024

mhdawson mentioned this pull request Oct 28, 2024

Node.js Technical Steering Committee (TSC) Meeting 2024-10-30 nodejs/TSC#1643

Closed

Merge branch 'main' into feat/stream-guide

09cc405

ovflowd added the github_actions:pull-request Trigger Pull Request Checks label Oct 28, 2024

github-actions bot removed the github_actions:pull-request Trigger Pull Request Checks label Oct 28, 2024

ovflowd deployed to Storybook October 28, 2024 21:32 — with GitHub Actions View deployment

vercel bot deployed to Preview October 28, 2024 21:34 View deployment

vercel bot deployed to Preview November 14, 2024 07:47 View deployment

ovflowd reviewed Nov 16, 2024

View reviewed changes

ovflowd approved these changes Nov 16, 2024

View reviewed changes

Merge branch 'main' into feat/stream-guide

5e4b3d7

ovflowd added the github_actions:pull-request Trigger Pull Request Checks label Nov 16, 2024

github-actions bot removed the github_actions:pull-request Trigger Pull Request Checks label Nov 16, 2024

ovflowd deployed to Storybook November 16, 2024 13:43 — with GitHub Actions View deployment

vercel bot deployed to Preview November 16, 2024 13:44 View deployment

avivkeller reviewed Nov 16, 2024

View reviewed changes

Apply suggestions from code review

8f76b2a

Co-authored-by: Aviv Keller <[email protected]> Signed-off-by: Carlos Espa <[email protected]>

vercel bot deployed to Preview November 17, 2024 09:28 View deployment

fixup! Apply suggestions from code review

0c3afaa

vercel bot deployed to Preview November 17, 2024 10:22 View deployment

fixup! fixup! Apply suggestions from code review

6d9c6b4

vercel bot deployed to Preview November 17, 2024 11:15 View deployment

avivkeller mentioned this pull request Nov 18, 2024

feat(learn): add Package Configuration article #7229

Merged

mhdawson mentioned this pull request Nov 18, 2024

Node.js Technical Steering Committee (TSC) Meeting 2024-11-20 nodejs/TSC#1652

Closed

mhdawson mentioned this pull request Nov 25, 2024

Node.js Technical Steering Committee (TSC) Meeting 2024-11-27 nodejs/TSC#1656

Closed

mhdawson mentioned this pull request Dec 2, 2024

Node.js Technical Steering Committee (TSC) Meeting 2024-12-04 nodejs/TSC#1660

Closed

mhdawson removed the tsc-agenda label Dec 4, 2024

styfle reviewed Dec 5, 2024

View reviewed changes

mcollina approved these changes Dec 21, 2024

View reviewed changes

feat: add streams guide #7123

Are you sure you want to change the base?

feat: add streams guide #7123

Conversation

Ceres6 commented Oct 16, 2024

Description

Validation

Related Issues

Check List

vercel bot commented Oct 16, 2024 • edited Loading

Ceres6 commented Oct 16, 2024

AugustinMauroy commented Oct 16, 2024

Ceres6 commented Oct 16, 2024

AugustinMauroy commented Oct 16, 2024

Ceres6 commented Oct 21, 2024

mcollina commented Oct 21, 2024

simoneb commented Oct 22, 2024

mcollina commented Oct 25, 2024

mcollina commented Oct 25, 2024 • edited Loading

Ceres6 commented Oct 25, 2024 • edited Loading

mcollina commented Oct 25, 2024

Ceres6 commented Oct 25, 2024

mcollina commented Oct 25, 2024

ovflowd commented Oct 28, 2024

github-actions bot commented Oct 28, 2024 • edited Loading

github-actions bot commented Oct 28, 2024 • edited Loading

Unit Test Coverage Report

Unit Test Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ovflowd left a comment

Choose a reason for hiding this comment

avivkeller left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

avivkeller commented Nov 17, 2024

Ceres6 commented Nov 17, 2024

avivkeller commented Nov 17, 2024

Ceres6 commented Nov 26, 2024

styfle Dec 5, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ovflowd commented Dec 16, 2024

simoneb commented Dec 18, 2024 • edited Loading

ovflowd commented Dec 18, 2024

mcollina left a comment

Choose a reason for hiding this comment

mcollina commented Dec 21, 2024

vercel bot commented Oct 16, 2024 •

edited

Loading

mcollina commented Oct 25, 2024 •

edited

Loading

Ceres6 commented Oct 25, 2024 •

edited

Loading

github-actions bot commented Oct 28, 2024 •

edited

Loading

github-actions bot commented Oct 28, 2024 •

edited

Loading

styfle Dec 5, 2024 •

edited

Loading

simoneb commented Dec 18, 2024 •

edited

Loading