doc: Documenting known issues and discrepancies

[ronag]

We have a few strange behaviours that we won't fix or have not yet fixed due to time limitations or compatibility concerns.

A common one is e.g. the callback parameter to different stream methods that have discrepancies such as:

• callback is not always invoked.
• callback does not always error when we might actually expect it to.
• callback does not always error with the error we might actually expect it to.
• callback with error does not always emit 'error'.
• callback is not always invoked asynchronously.

Should we add descriptions for these edge cases possibly inside some kind of markdown block with a comment about when these are relevant, might be fixed in the future and recommendations on how to workaround them while at the same remaining as compatible as possible with future fixes. Including a "doc backport" into previous versions. This would possibly also help with migrating the ecosystem away from assumptions based on these discrepancies.

My main concern with this is that users might start depending on these "incorrect" behaviours which might make them even more difficult to fix, i.e. the exact opposite of the original intention.

I do appreciate that this adds additional maintenance, but maybe we can be explicit about that these comments are not complete and added on best effort basis.

Some of these issue are of course documented indirectly in our issue tracker but I'm I don't think most users will actually look and find the relevant issues in the tracker.

[ronag]

Having written this down it occurs to me that this is a very nice to have in theory but probably unmanageable in practice.