[docs] add warnings about input, stdin, and stdio

[jedwards1211]

• warn about and explain behavior when combining input/fileInput with stdin: 'inherit' or stdio: 'inherit'
• warn about upcoming stdio: [..., 'ipc'] deprecation

fix #1218

[ehmicky]

Could you please remove both > and [!IMPORTANT]/[!NOTE]? It's not a bad thing, but it's not consistent with the rest of the documentation, which does not use this style. Thanks!

[ehmicky]

Execa has quite a lot of features, which can make its documentation a little overwhelming. So we're making sure the documentation remains concise and we typically explain each piece of information only once. We also mostly avoid repeating between the api.md and rest of the documentation, and rely on users following the "More info" link instead.

Based on this, could you please write the information related to ipc in a single place, as opposed to three? The best place would be ipc.md.

[jedwards1211]

I don't really want to; this is the warning I would want to see as a busy developer already familiar with the child_process API encountering this library for the first time. I see burying the warning as a disservice to other experienced developers. I find it kind of annoying that y'all don't seem concerned that having subtle differences is going to cause some developers frustration

[jedwards1211]

Maybe I should calm down, but I guess the other thing that bothers me is, it's a real shame to abandon being a superset of the child_process.spawn API, that was a nice feature to me because that API is much simpler than execa has become and well known, so at least I can be sure what I'm getting in cases when I don't use any of execa's additional options. Maybe I should just go back to my old package that's a thinner clone of child_process plus promises...

[ehmicky]

For concision, let's assume users read this file in its entirety. If so, they will read that section below, so we do not need to point to it from those 3 sections above (and also the 2 places in api.md). This will also help keep this documentation page concise.

[jedwards1211]

Can we move the section higher in the document then? I'm trying to look out for busy devs like me who just tend to skim for what we're looking for.

Again, because the API has been a superset of child_process.spawn, I really think devs can be forgiven for assuming they can get away without much RTFM in a case like this

[ehmicky]

Thanks @jedwards1211!

This is very helpful. I've added a few comments to try to keep the PR small, and also consistent with the rest of the documentation.

[ehmicky]

Hi again @jedwards1211,

We're back from the holidays! 🎄
I've pushed a documentation change at #1222 and #1221, which should solve this PR and #1218.

Thanks again for raising this issue and working on this PR. 🙏

[jedwards1211]

Thanks. Honestly I think y'all should completely remove the stdio option if you're going to stop supporting a superset of child_process.spawn options.

In child_process.spawn it's conceptually very clear, all of the child's stream config goes into one property, stdio.

In execa y'all have split the child's stream config up into stdin, stdout, stderr, ipc, input, (etc?) properties in addition to stdio.

This makes the behavior when both stdio and some of those other options are passed more complicated to implement and to document.

Dropping support for stdio would simplify that cruft and make the difference from child_process.spawn more obvious.

Letting Sindre dictate what he wants without providing any concrete rationale why left a bad taste in my mouth. 8 years of aligning with the standard library, and then one day, deciding not to for ..some.. reason