[FFmpeg-devel] [RFC PATCH v2 0/1] avutil/error: Provide better feedback about unknown error codes

[Andrew Sayers]

I'm having trouble managing this conversation.  On one hand, you've brought up
several important details that would need to be included in a new patch.
On the other hand, I'm pretty sure we're talking past each other on the big
problems, and need to start over.  So let's fork the discussion.

# First, let's haggle over some details

The patch below fixes a number of small issues brought up by your comments...

Error numbers are always expressed in the code as either uppercase hex numbers
or FourCCs (or ThreeCCs, but you get the point).  This patch prints error codes
as hex, which is no less unintelligible for ordinary users, might make problems
easier to find on Google, and will sometimes make them easier to grep for.

Having said that, this patch prints non-negative numbers in decimal,
because all bets are off if that manages to happen.

A developer could create an error code that just happens to be valid ASCII.
In that situation, the previous patch would have printed something like
"Unrecognised error code \"~!X\"" occurred", which is worse than the current
behaviour.  This patch includes both (hex) number and name in those messages.

This patch adds "please report this bug" for all unknown error messages.
I'll cover the reasoning below, but the relevant detail is that the previous
patch just gave users a different heiroglyphic before abandoning them.

# Second, let's talk about the big picture

Consider the following scenario:

1. a new developer adds some code to FFmpeg that calls an existing function
2. it turns out that function sometimes calls another function that
   returns a variety of internal error codes (FFERROR_REDO among others)
3. their testing uncovers a situation that intermittently returns an unknown
   error number, but they don't notice there are two different numbers
4. they spend a lot of time tracking down an error message based on a random
   number, and eventually fix "the" bug (actually one of two intermittent bugs)
5. the review doesn't catch the other bug, and the new code goes live
6. a user trips over the other bug and sees "Error number <number> occurred"
7. the user wastes a lot of time trying to work out what they did wrong,
   badmouthing FFmpeg to anyone who will listen as they do
8. they eventually catch the attention of a developer
9. that developer spends a lot of time bisecting the bug
10. the new developer is expected to fix this patch, and feels like they're
    to blame for the whole situation

An error message like "Unrecognised error code \"REDO\" occurred, please report
this bug" would give the newbie a fighting chance to catch both bugs at step 3,
would make step 4 much shorter, and would optimise steps 7-10 to almost nothing.

Catching this in a fate test would involve checking for an unknown function
returning an unknown number that gets reused in a context it's subtly
inappropriate for.  I have no idea where to begin with that, and anyway it
wouldn't help a developer in the process of tracking down an intermittent bug.

As mentioned above, the v2 patch adds "please report this bug" in a few places.
Any negative error code can be valid, but returning a raw error number is always
a bug, so it's all the same to users - if they see this message, they're not
expected to fix it themselves, they're expected to let us know.