Document long-term technical debt

[piscisaureus]

There are longstanding known issues in node which are (mostly) in my head only.
For some of them there currently isn't a plan on how to prioritize them.
It feels futile to open issues for these topics, because they'll be buried soon under a pile of short-term, actionable bug reports.

The goal here is to capture some tacit knowledge and share with more people.

An example (which would be documented in much more detail):

• The process IPC doesn't support backpressure and silently drops messages when overloaded.

Many of the things I know about are actually windows issues:

• Cluster is very inefficient on windows (I know why - long story).
• The IPC pipe implementation in libuv is a mess
• fs.chmod() probably doesn't do the right thing
• Command line formatting (for child_process.exec) could be improved to work better for batch files.

I would not mind setting myself down to document what I know and submit it as a PR. But would it be helpful/worthwhile? Please advise @nodejs/tsc.

[Fishrock123]

maybe we should we have wiki page this for collaborator use?

[indutny]

Unmess debugger? :)

[rvagg]

Domains, it's invasive but not really deprecatable at this stage at least--a path to make them less invasive or properly deprecate and remove?

[Qard]

👍 On putting this stuff in collaborator docs somewhere.

@trevnorris and I are wanting to get some documentation put together on internals, dependencies and such, so this would be very relevant to us.

[jasnell]

+1 to using a doc somewhere to list this. Adding a doc to the repo ought to
work tho.
On May 25, 2015 4:36 PM, "Stephen Belanger" [email protected]
wrote:

[image: 👍] On putting this stuff in collaborator docs somewhere.

@trevnorris https://github.com/trevnorris and I are wanting to get some
documentation put together on internals, dependencies and such, so this
would be very relevant to us.

—
Reply to this email directly or view it on GitHub
#1795 (comment).

[chrisdickinson]

I've been poking at building out a "doc/internal" dir, to contain things like this. There's going to be a node doc meetup at nodeconf this year with the goal of producing a comprehensive IA for the docs, internal and external. In the meantime a "doc/internal/todo.md" would likely suffice!

On May 25, 2015, at 5:33 PM, James M Snell [email protected] wrote:

+1 to using a doc somewhere to list this. Adding a doc to the repo ought to
work tho.
On May 25, 2015 4:36 PM, "Stephen Belanger" [email protected]
wrote:

[image: 👍] On putting this stuff in collaborator docs somewhere.

@trevnorris https://github.com/trevnorris and I are wanting to get some
documentation put together on internals, dependencies and such, so this
would be very relevant to us.

—
Reply to this email directly or view it on GitHub
#1795 (comment).

—
Reply to this email directly or view it on GitHub.

[jasnell]

+1 to doc/internal/

[domenic]

Alternately it might be worth opening separate issues (with more details) to give people a place to collaborate on a specific issue. Then, tagging them all with a specific tag, and linking to that tag from some kind of docs.

[sam-github]

• cluster.kill() is deceiving
• url.format property names are a trap (parse, set .host, format, watch it do nothing... because you didn't delete .hostname)

[Fishrock123]

We should be able to put this stuff into https://github.com/nodejs/docs for now. @piscisaureus mind writing and PRing your stuff to somewhere within src/ there?

If anyone else has info dumps, that's probably also the target place for now. :)

[trevnorris]

If there are a lot off problems, then I like the idea of each having its own issue. Though if that happens then I'd also like its own repo or such. Having those scattered throughout here would be a pain.

[Qard]

You could just tag them with a tech-debt tag or something. Having an entirely separate repo would be weird.

[Fishrock123]

Having never ending issues is not a good idea imo.

The docs repo is already separate, why not do it in there?

[trevnorris]

@Qard It really would depend on the number of issues. I doubt we'd get enough to merit that. Was also thinking it could go along well w/ something like internal docs or whatnot where all this stuff could be cataloged.

[Qard]

True, it would probably fit well in the internals docs section of the docs wg stuff. I'm 👍 for putting it there.

[Fishrock123]

@piscisaureus Now that you are back more do you think you could do some of this?

The current location would be https://github.com/nodejs/new.nodejs.org/tree/master/locale/en/docs/meta/topics (Public as https://nodejs.org/en/docs/meta/topics/dependencies/, but not necessarily linked to on the website)

Ala https://github.com/nodejs/docs/blob/master/GETTING-STARTED.md#what-we-write

If that doesn't work we should make sub-directories like that in the docs folder here.

[jasnell]

Closing this due to lack of activity. This is generally a good idea but there's no reason to keep this open.