Suggestions

[tooolbox]

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.
• [x] 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.
• [x] 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.
• [x] 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!

[knz]

Your suggestions are valuable. Thanks for taking the time to formulate them as an actionable list.

[knz]

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.

Done in commit b33d88a