Could have more guidance on the style guide around errors

[schneems]

Here's some notes I took from an internal review

Notes

• Internal review link [Heroku employees only] Prior work: https://docs.google.com/document/d/1uixuWY91bRl4BX1eIdsPpkPAc3j5g6KYdGGYyCEf7lY/edit
  • Can use "View history" to see old conversations
• Ruby errors https://github.com/heroku/buildpacks-ruby/blob/f6a5be3b1d7b0f581db298e0c4f8404d8e02048a/buildpacks/ruby/src/user_errors.rs
  • Note this doesn't use bullet stream (yet)
• Guidance for styles lives in https://github.com/schneems/bullet_stream/blob/main/examples/style_guide.rs. If there's something we can add there, we should.
• Try really hard to add a resolution or action item for every error. Try to make errors actionable. Sandy kept asking "What's the resolution"
• The error message should come last and the user should not have to scroll for it
  • Because debug info can be much longer, it should come above the final error message
• State the problem, state how we know/see it's a problem, state why that problem means we cannot continue.
• Give additional information about the failure that could help with debugging. For example:
  • if a file doesn't exist in a directory, output the contents of the directory: https://github.com/heroku/buildpacks-ruby/blob/f6a5be3b1d7b0f581db298e0c4f8404d8e02048a/buildpacks/ruby/src/user_errors.rs#L113-L121
  • If a command fails to be found by the system, emit PATH debugging info https://github.com/heroku/buildpacks-ruby/blob/f6a5be3b1d7b0f581db298e0c4f8404d8e02048a/buildpacks/ruby/src/steps/rake_assets_install.rs#L108
  • Annotate tool specific config for output https://github.com/heroku/buildpacks-ruby/blob/f6a5be3b1d7b0f581db298e0c4f8404d8e02048a/buildpacks/ruby/src/user_errors.rs#L290-L292.
• Encourage local debugging when possible https://github.com/heroku/buildpacks-ruby/blob/f6a5be3b1d7b0f581db298e0c4f8404d8e02048a/buildpacks/ruby/src/user_errors.rs#L231
• Link to doc urls when possible
• Don't ask people to retry something just because it's something to try unless we know that there's an intermittent component and retrying is actually a useful effort. It's frustrating to see "please try again" if it will never work
  • Direct people to status pages when relevant, for example https://github.com/heroku/buildpacks-ruby/blob/f6a5be3b1d7b0f581db298e0c4f8404d8e02048a/buildpacks/ruby/src/user_errors.rs#L163-L169
  • And https://github.com/heroku/buildpacks-ruby/blob/f6a5be3b1d7b0f581db298e0c4f8404d8e02048a/buildpacks/ruby/src/user_errors.rs#L28-L30
• Don't tell people to file issues with the buildpack or support tickets by default, they'll do plenty of that without encouragement. The one area I mention this, I gave some guidance on when it's appropriate https://github.com/heroku/buildpacks-ruby/blob/f6a5be3b1d7b0f581db298e0c4f8404d8e02048a/buildpacks/ruby/src/user_errors.rs#L32-L34.
• Consider that errors will be seen both on Heroku and locally.

TODO

Memorialize those in the print getting started guide where appropriate. Collect other best practices from other buildpacks