Add design doc for error handling

[echeran]

Add design doc to contextualize the PR #795 based on the issue & discussion begun in #782 .

[echeran]

As discussed on yesterday's call, I think we need to require two different things:

1. An implementation must provide a way for a message with a runtime error to be formatted in a way that provides the user with that error.
2. An implementation must provide a way for a message with a runtime error to be formatted using a fallback representation.

These separate requirements could be fulfilled by a single formatting method, or by more than one such method.

@eemeli PTAL at the changes. See the discussion in this conversation within this PR where I address this. Also take a look at the wording and rationale for it based on our discussion in Monday's meeting, in particular my intent to be precise on what we're requiring & not, and whether that means the appropriate language is "returning"/"emitting"/"signalling" an error.

[echeran]

This document continues to not present and consider the alternative discussed on the call and in my preceding comment, of separating the two MUST requirements more clearly from each other.

You did say that, although even after consulting the notes from the meeting, I couldn't understand what you meant by separating the 2 MUST requirements more clearly. If it's a matter of saying that you can satisfy the intended requirements in different ways, including having 2 APIs side-by-side in which one is stricter and signals an error while the other is permissive and always returns a best-effort value, the proposed alternative does that.

The only thing that seemed close to matching your description of what you'd like is the following excerpt from the meeting's notes doc, which sounds much like the current text, so I didn't really see its distinguishing features enough to make it a new alternative:

EAO: My position is that we should impose some requirements on implementations - what they must be able to provide. The way I would put the requirements - there must be a way to format the message that you get a fallback and that you must be able to format the message and get failure reported to you somehow. This would require behaviors from the implementer.

If you can write out the alternative you're thinking with pros & cons listed, I would be okay adding it.

[eemeli]

This document continues to not present and consider the alternative discussed on the call and in my preceding comment, of separating the two MUST requirements more clearly from each other.

You did say that, although even after consulting the notes from the meeting, I couldn't understand what you meant by separating the 2 MUST requirements more clearly. If it's a matter of saying that you can satisfy the intended requirements in different ways, including having 2 APIs side-by-side in which one is stricter and signals an error while the other is permissive and always returns a best-effort value, the proposed alternative does that.

While the proposed alternative does allow for an API as you describe, it does not require that a fallback representation is made available. The spec text that's currently proposed

In all cases, when encountering an error, a message formatter MUST be able to signal an error or errors. It MAY also provide the appropriate fallback representation of the message defined in this specification.

allows for a formatter that either returns the formatted result or null on error, as the latter can act as a signal that an error has occurred. This is not sufficient.

The requirement of a way to get a formatted representation of messages with runtime errors is important, because it needs to be accounted for in the formatter design: A formatter cannot just bail on the first error, but must have the capability of continuing to format a message past the first error.

The inclusion of "In all cases" also does not make it clear that an implementation providing two formatting methods (a strict thrower and a lenient fallback formatter) would be valid, given that formatting with the latter would not necessarily signal any error. This is an aspect of the current spec language that I believe for us to have consensus on fixing.

If you can write out the alternative you're thinking with pros & cons listed, I would be okay adding it.

I'll see if I have time for that later this week, but it may take until next week.

[aphillips]

In the 2024-06-24 call we agreed to accept this design with some changes. Waiting on changes/approvals to merge. @eemeli will then have an action to update the spec.