Document this library's approach to GitHub API rate limit

[PauloMigAlmeida]

Even for people that know certain bits and pieces of this library's source code, it still not trivial to understand how this library deals with GitHub's API rate limit.

I'm planning to write something about it as soon as the #595 is merged (as it may introduce the custom api rates)

[Hronom]

Please do this, we need to use rate limit and make client wait if it about to hit them

[bitwiseman]

@Hronom

Help would be appreciated.

There is the rate limit checker and the abuse limit checker. More recently, GitHub has added more ephemeral rate limiting they call secondary rate limiting. It behaves somewhere like abuse limiting, the metric is not publicly reported on an API level, but clients are expected to adhere to it anyway. 😭 😡

I've filed #1975 to track work on improving the secondary rate limiting behavior.