|
| 1 | +# Node.js Web Team Meeting 2025-09-29 |
| 2 | + |
| 3 | +## Links |
| 4 | + |
| 5 | +* **GitHub Issue**: https://github.com/nodejs/web-team/issues/43 |
| 6 | + |
| 7 | +## Present |
| 8 | + |
| 9 | +* Aviv Keller @avivkeller |
| 10 | +* Claudio Wunder @ovflowd |
| 11 | +* Alex Bit @alexbit-codemod (Guest, Userland Migrations) |
| 12 | +* Dario Piotrowicz @dario-piotrowicz |
| 13 | +* Matt Cowley @MattIPv4 |
| 14 | +* Rene @Renegade334 (Guest, TypeScript) |
| 15 | +* Jake Bailey @jakebailey (Guest, TypeScript) |
| 16 | +* Brian Muenzenmeyer @bmuenzenmeyer |
| 17 | +* Bruno Rodriguez @brunocroh (Guest, Userland Migrations) |
| 18 | + |
| 19 | +## Agenda |
| 20 | + |
| 21 | +* Extracted from **web-agenda** labelled issues and pull requests from the **nodejs org** prior to the meeting. |
| 22 | + |
| 23 | + |
| 24 | +### nodejs/nodejs.org |
| 25 | + |
| 26 | +* content(`userland-migration`): make up to date [#8053](https://github.com/nodejs/nodejs.org/pull/8053) |
| 27 | + * Alex, Codemod explanation. Codemods are only used when they are officially endorsed |
| 28 | + * Alex, plan: |
| 29 | + * "Userland Migrations" blog cat |
| 30 | + * Migration guides |
| 31 | + * Changelogs |
| 32 | + * See other frameworks, like React, for inspiration |
| 33 | + * "Userland Migrations" learn |
| 34 | + * What is a codemod? |
| 35 | + * Basic description |
| 36 | + * **Not for migration guides** |
| 37 | + * Use Docs banner for migration guides |
| 38 | + * Claudio, Migrations don't need to go in Learn, it's for concepts, not "things" |
| 39 | + * Leave things light, people can use MDN for specifics |
| 40 | + * Release/Other blog posts are the ideal place for these |
| 41 | + * (Aviv +1) |
| 42 | + * It's important to understand that certain blog posts must come from a certain team, that's not entirely in the website team's control. Perhaps get in touch with Releasers and/or Marketing. |
| 43 | + * Brian, can we add banners _after_ the fact, since Codemod's take time to develop |
| 44 | + * Claudio, true, Codemod's won't be instantly ready, we'd need to change the banner dynamically. |
| 45 | + |
| 46 | +### nodejs/doc-kit |
| 47 | + |
| 48 | +* Generate Type Declarations [#437](https://github.com/nodejs/doc-kit/issues/437) |
| 49 | + * Brian, why doesn't Node.js ship its own types |
| 50 | + * Claudio, no runtime does, each provides out-of-house |
| 51 | + * It's hard for the system to know _which_ version of Node.js you are using, and thus, another package is ideal |
| 52 | + * It's hard to identify _where_ the types are |
| 53 | + * Jake, if it were bundled, we (Node.js) would be responsible for a lot of compat we aren't expert in |
| 54 | + * Current issues: |
| 55 | + * "Goofy" types for cross-compat with the DOM |
| 56 | + * Too many manual changes |
| 57 | + * The script doesn't really use the docs *super* often |
| 58 | + * Claudio, we would like to reduce the manual work |
| 59 | + * New engine (`doc-kit`) can infer interfaces |
| 60 | + * Aviv, while making `doc-kit`, we noticed many issues with the current Structure |
| 61 | + * Rene, the source is _human_ readable, but not very _machine_ readable |
| 62 | + * Current tooling can't do multiple types in a single Array, i.e. `buffer.Blob` |
| 63 | + * It's hard to interop with the Web API |
| 64 | + * Making it machine readable it's fruitful, since it'll still need changes in TypeScript |
| 65 | + * Documentation isn't the primary focus of code review |
| 66 | + * If the docs were strongly-typed, it would help, but it would make them extremely rigid. |
| 67 | + * Claudio, this is something we can and should change |
| 68 | + * Jake, types are also generic, when, in reality, they are different in various TypeScript versions. |
| 69 | + * In TS's DOM Lib, the raw spec is taken, converted to types, and patches are applied on top. |
| 70 | + * Brian, even if we don't make it perfect and hands-off, we can make it better |
| 71 | + * Aviv, we should bring these types to the collaborators, and work to make the docs rigid |
| 72 | + * Rene, unless there is a shift in code review, that'll always be a problem |
| 73 | + * We could, however, build better types in the markdown |
| 74 | + * Claudio, we have AST in our new generator to create very precise JSON |
| 75 | + * We can make this format entirely our own, as consumable and reliable as possible |
| 76 | + * It's worth it to make the DX high and the pain low |
| 77 | + * Claudio, DefinitelyTyped can import `doc-kit` for their parsing |
| 78 | + * Aviv, we can add a generator to put it in a format best of them |
| 79 | + * Claudio, we can lint the docs to make their types compatible |
| 80 | + * Rene, we can leverage this, but garbage in -> garbage out |
| 81 | + * It'll cause an awful lot of upstream changes |
| 82 | + * Aviv's PR to use the same list format was an example of something that helped standardize |
| 83 | + * The primary objective is to make the docs readable for DT maintainers |
| 84 | + * Claudio, if you (Rene + Jake) can look over the codebase, and find what stands out, and what is needed, now is the best time to make changes |
| 85 | + * We appreciate DTS, and we want to give back |
| 86 | + * We have the ability to do so much |
| 87 | + * We do need to, however, change the status quo on the docs |
| 88 | + |
| 89 | +### nodejs/web-team |
| 90 | + |
| 91 | +* Create Means for Private Communications [#14](https://github.com/nodejs/web-team/issues/14) |
| 92 | + |
| 93 | + * Skipped as we ran out of time |
| 94 | + |
| 95 | +## Upcoming Meetings |
| 96 | + |
| 97 | +* **Node.js Project Calendar**: <https://nodejs.org/calendar> |
| 98 | + |
| 99 | +Click `+GoogleCalendar` at the bottom right to add to your own Google calendar. |
0 commit comments