Suggestions

Inizia esaminando il README del repository e la sezione collegata sulla migrazione degli errori in docs/RFCS/20190318_error_handling.md, quindi verifica come vengono attualmente presentati exthttp ed extgrpc. L’issue contiene molti suggerimenti separati, quindi individua prima un’unica modifica alla documentazione condivisa. Il lavoro sarà completato quando sarà disponibile un aggiornamento mirato con esempi o link coerenti con l’ambito scelto.

For @knz

I was looking through the docs trying to find out how to register a migrated error, and it took me a little bit. So I wanted to suggest how to make that more visible, and then I thought while I'm at it, a couple more suggestions:

• First, the docs on migrating/renaming an error are a little buried and could perhaps be linked in the README. You talk about forward compatibility in the README, which I understand in part to involve forwarding errors through unaware intermediaries but from the name it sounds like error migration is part of it, so I was surprised how much I had to dig to re-find this data.
• RegisterTypeMigration could perhaps be part of the "forwarded methods" so it shows up in the main package, looks like I currently need to import errbase to get at it.
• The README could use a sample of the ultra-awesome stack trace format!
• The compatibility table is a bit intense to be at the top of the README. I remember back when I first came across this package, it was a little confusing—my takeaway was, "wow, this thing has lots of features I guess". I feel like you might be better served by having the top of the README dedicated to a simple bullet-point list of features and some code samples showing what it looks like in practice.
• Could have a godoc badge up at the top of the README:
• Perhaps rethink how the data on custom errors is provided. The information is pretty dense and unstructured; I would suggest more subheadings for specific tasks like "Custom Leaf", "Custom Wrapper", "Over the Network", or some such. Also perhaps consider putting the writeup in its own document because there's a lot to the subject and it can be overwhelming to someone landing on the main page of the repo.
• This is subjective, but I think in general the README could express more through code samples:
  • The section on Available Error Leaves could show little fake error scenarios, using that applicable function, and then retrieving the data, with additional details in comments.
  • The section How to Use could perhaps be shown in code.
• I question the necessity of API (not constructing error objects), since Godoc is probably better suited for this anyway.
• I don't think the exthttp package is mentioned as a useful tool, more as an example for when you're building your own error types, but I think it adds value. Also extgrpc isn't mentioned, although that one's entirely my fault because I never added docs for the work I did 😉
• I feel like the project deserves a cool logo! (😄 ) Maybe a variation of the cockroachdb logo?

I'm aware that I'm armchair-quarterbacking and should probably put a PR where my mouth is, but I'm in the middle of other things and just felt compelled to jot down some notes. Interested to hear your thoughts!