feat: add streams guide #7123
feat: add streams guide #7123
Conversation
Co-authored-by: Matteo Collina <[email protected]>
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
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 |
I mean you just have to update |
|
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? |
|
@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. |
@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.
I think the question for the @nodejs/tsc is:
(We should not be using existing material without the author permission anyway). |
|
Here is a proposal, how about you include in the commit description:
So we keep a record of the origin of this content. |
|
@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? |
|
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 
|
|
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 |
|
I would list them all. |
|
Hey folks 👋 are we happy here? |
github-actions
bot
removed
the
github_actions:pull-request
|
Lighthouse Results
|
Unit Test Coverage Report
Unit Test Report
|
|
@mcollina Should I add the backlink so we can merge this and we can revisit it if the tsc votes otherwise? |
|
My opinion is that we should include something like "This content was originally shared by Y in X" |
|
I think we should also document in the collaborator guide for the Node.js website that we should include references when pulling in content from other sources. That process should also be to make sure we document that the original author is ok with the content being pulled in, possibly through approving the PR that pulls it in. |
Add authors and original content attribution Signed-off-by: Carlos Espa <[email protected]>
|
Authors and original attribution added. Are we good to go, @mcollina? |
| @@ -323,6 +323,10 @@ | |||
| "backpressuringInStreams": { | |||
| "link": "/learn/modules/backpressuring-in-streams", | |||
| "label": "components.navigation.learn.modules.links.backpressuringInStreams" | |||
| }, | |||
| "howToUseStreams": { | |||
There was a problem hiding this comment.
This learn page should be before backpressure in streams IMO.
There was a problem hiding this comment.
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
github-actions
bot
removed
the
github_actions:pull-request
| [`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 |
There was a problem hiding this comment.
Some links are inline, while others are like this, can you make them all uniform?
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
There was a problem hiding this comment.
IMO as you said, having them at the bottom is cleaner
There was a problem hiding this comment.
I put them all at the end, hope that's okay
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]>
|
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 ) |
|
@mcollina did you have time to review it? |
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
npm run formatto ensure the code follows the style guide.npm run testto check if all tests are passing.npx turbo buildto check if the website builds without errors.