Document how and when the library raises exceptions

[timrogers]

This adds a section to the readme which explains when the library will raise exceptions and how you can work with them.

I did some work with octokit/octokit.rb and octokit/octokit.js recently, and I found that not having this meant that I had to do a bunch of digging myself to understand how I should handle unhappy paths.

As well as adding the error handling documentation, this PR also makes a few other small changes to the README: correcting, renaming and restructuring headings.

[nickfloyd]

Hey @timrogers thanks for these additions! I just left one small nit on the bulleted items for the errors. Let me know what you think!

[nickfloyd]

👍 LGTM! Side note - did you intend your base branch to be octokit:4-stable - This feels like the base should be master given it's just a docs change and not a hotfix.

[indigok]

👍 LGTM! Side note - did you intend your base branch to be octokit:4-stable - This feels like the base should be master given it's just a docs change and not a hotfix.

octokit:4-stable is still the correct branch! master has significantly diverged at this point 😄

[timrogers]

I'm not allowed to merge this, which I'm guessing is due to the outstanding GitHub checks (which aren't needed due to the ci skip!).

I'll just let the checks run for the last commit to get around this 🙏

[timrogers]

octokit:4-stable is still the correct branch! master has significantly diverged at this point 😄

Interesting! 🤔 Is there some clean-up we can or should do here? Perhaps we could delete master and create a new main branch starting from 4-stable?

[nickfloyd]

Interesting! 🤔 Is there some clean-up we can or should do here? Perhaps we could delete master and create a new main branch starting from 4-stable?

Yeah, we've got plans to get things cinched up around builds, workflow, and CI. Great work has already been done on octokit Ruby; it will take a bit of effort, but I am definitely looking forward to tackling things like these so that we can get this to a point where it is up to date and more welcoming to contributors!

[timrogers]

Interesting! 🤔 Is there some clean-up we can or should do here? Perhaps we could delete master and create a new main branch starting from 4-stable?

Yeah, we've got plans to get things cinched up around builds, workflow, and CI. Great work has already been done on octokit Ruby; it will take a bit of effort, but I am definitely looking forward to tackling things like these so that we can get this to a point where it is up to date and more welcoming to contributors!

Wonderful! 🙌🏻

[timrogers]

@nickfloyd This should be ready for merge now. Thank you so much!

[imwiss]

Thanks for updating this, @timrogers! ✨