From 0c2af3ca2d0d6f78f1959cd4d6b59ebfd8a009c6 Mon Sep 17 00:00:00 2001 From: Carlos Alexandro Becker Date: Thu, 8 Dec 2016 17:11:06 -0200 Subject: [PATCH 01/10] deal with 202 --- github/github.go | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/github/github.go b/github/github.go index d96fa85c83b..66a594b1b4a 100644 --- a/github/github.go +++ b/github/github.go @@ -501,6 +501,15 @@ func (r *RateLimitError) Error() string { r.Response.StatusCode, r.Message, r.Rate.Reset.Time.Sub(time.Now())) } +// AcceptedError occurs when GitHub returns 202 Accepted response with an +// empty body, which means a job was scheduled on the GitHub side to process +// the information needed and cache it. +type AcceptedError struct{} + +func (r *AcceptedError) Error() string { + return "Job scheduled on GitHub side, try again later" +} + // AbuseRateLimitError occurs when GitHub returns 403 Forbidden response with the // "documentation_url" field value equal to "https://developer.github.com/v3#abuse-rate-limits". type AbuseRateLimitError struct { @@ -603,6 +612,8 @@ func CheckResponse(r *http.Response) error { abuseRateLimitError.RetryAfter = &retryAfter } return abuseRateLimitError + case r.StatusCode == http.StatusAccepted: + return &AcceptedError{} default: return errorResponse } From 615c613ba1c23aba5f0b7918b188e346fb69bab7 Mon Sep 17 00:00:00 2001 From: Carlos Alexandro Becker Date: Fri, 9 Dec 2016 09:44:03 -0200 Subject: [PATCH 02/10] improved messages, unused pointer, etc --- github/github.go | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/github/github.go b/github/github.go index 66a594b1b4a..75a9915f021 100644 --- a/github/github.go +++ b/github/github.go @@ -504,10 +504,13 @@ func (r *RateLimitError) Error() string { // AcceptedError occurs when GitHub returns 202 Accepted response with an // empty body, which means a job was scheduled on the GitHub side to process // the information needed and cache it. +// Technically, 202 Accepted is not a real error, it's just used to +// indicate that results are not ready yet, but should be available soon. +// The request can be repeated after some time. type AcceptedError struct{} -func (r *AcceptedError) Error() string { - return "Job scheduled on GitHub side, try again later" +func (AcceptedError) Error() string { + return "job scheduled on github side, try again later" } // AbuseRateLimitError occurs when GitHub returns 403 Forbidden response with the @@ -573,14 +576,18 @@ func (e *Error) Error() string { } // CheckResponse checks the API response for errors, and returns them if -// present. A response is considered an error if it has a status code outside -// the 200 range. API error responses are expected to have either no response +// present. A response is considered an error if it has a status code outside +// the 200 range or equal to 202 Accepted. +// API error responses are expected to have either no response // body, or a JSON response body that maps to ErrorResponse. Any other // response body will be silently ignored. // // The error type will be *RateLimitError for rate limit exceeded errors, // and *TwoFactorAuthError for two-factor authentication errors. func CheckResponse(r *http.Response) error { + if r.StatusCode == http.StatusAccepted { + return AcceptedError{} + } if c := r.StatusCode; 200 <= c && c <= 299 { return nil } @@ -612,8 +619,6 @@ func CheckResponse(r *http.Response) error { abuseRateLimitError.RetryAfter = &retryAfter } return abuseRateLimitError - case r.StatusCode == http.StatusAccepted: - return &AcceptedError{} default: return errorResponse } From 936aa01eacbcdf227313bd008493de6f1e2859af Mon Sep 17 00:00:00 2001 From: Carlos Alexandro Becker Date: Fri, 9 Dec 2016 16:14:39 -0200 Subject: [PATCH 03/10] pointer again, docs --- github/github.go | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/github/github.go b/github/github.go index 75a9915f021..9c36013d8b6 100644 --- a/github/github.go +++ b/github/github.go @@ -509,7 +509,7 @@ func (r *RateLimitError) Error() string { // The request can be repeated after some time. type AcceptedError struct{} -func (AcceptedError) Error() string { +func (*AcceptedError) Error() string { return "job scheduled on github side, try again later" } @@ -583,10 +583,11 @@ func (e *Error) Error() string { // response body will be silently ignored. // // The error type will be *RateLimitError for rate limit exceeded errors, +// *AcceptedError for 202 Accepted status codes, // and *TwoFactorAuthError for two-factor authentication errors. func CheckResponse(r *http.Response) error { if r.StatusCode == http.StatusAccepted { - return AcceptedError{} + return &AcceptedError{} } if c := r.StatusCode; 200 <= c && c <= 299 { return nil From 0c97936fb6bd822ef0fdb605c49276b2539696cf Mon Sep 17 00:00:00 2001 From: Carlos Alexandro Becker Date: Fri, 9 Dec 2016 16:29:37 -0200 Subject: [PATCH 04/10] repos stats docs --- github/repos_stats.go | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/github/repos_stats.go b/github/repos_stats.go index e4f75a5b080..81818d80c05 100644 --- a/github/repos_stats.go +++ b/github/repos_stats.go @@ -39,7 +39,7 @@ func (w WeeklyStats) String() string { // deletions and commit counts. // // If this is the first time these statistics are requested for the given -// repository, this method will return a non-nil error and a status code of +// repository, this method will return an *AcceptedError and a status code of // 202. This is because this is the status that github returns to signify that // it is now computing the requested statistics. A follow up request, after a // delay of a second or so, should result in a successful request. @@ -78,7 +78,7 @@ func (w WeeklyCommitActivity) String() string { // starting on Sunday. // // If this is the first time these statistics are requested for the given -// repository, this method will return a non-nil error and a status code of +// repository, this method will return an *AcceptedError and a status code of // 202. This is because this is the status that github returns to signify that // it is now computing the requested statistics. A follow up request, after a // delay of a second or so, should result in a successful request. @@ -104,6 +104,12 @@ func (s *RepositoriesService) ListCommitActivity(owner, repo string) ([]*WeeklyC // deletions pushed to a repository. Returned WeeklyStats will contain // additions and deletions, but not total commits. // +// If this is the first time these statistics are requested for the given +// repository, this method will return an *AcceptedError and a status code of +// 202. This is because this is the status that github returns to signify that +// it is now computing the requested statistics. A follow up request, after a +// delay of a second or so, should result in a successful request. +// // GitHub API Docs: https://developer.github.com/v3/repos/statistics/#code-frequency func (s *RepositoriesService) ListCodeFrequency(owner, repo string) ([]*WeeklyStats, *Response, error) { u := fmt.Sprintf("repos/%v/%v/stats/code_frequency", owner, repo) @@ -152,7 +158,7 @@ func (r RepositoryParticipation) String() string { // The array order is oldest week (index 0) to most recent week. // // If this is the first time these statistics are requested for the given -// repository, this method will return a non-nil error and a status code +// repository, this method will return an *AcceptedError and a status code // of 202. This is because this is the status that github returns to // signify that it is now computing the requested statistics. A follow // up request, after a delay of a second or so, should result in a @@ -185,6 +191,12 @@ type PunchCard struct { // ListPunchCard returns the number of commits per hour in each day. // +// If this is the first time these statistics are requested for the given +// repository, this method will return an *AcceptedError and a status code of +// 202. This is because this is the status that github returns to signify that +// it is now computing the requested statistics. A follow up request, after a +// delay of a second or so, should result in a successful request. +// // GitHub API Docs: https://developer.github.com/v3/repos/statistics/#punch-card func (s *RepositoriesService) ListPunchCard(owner, repo string) ([]*PunchCard, *Response, error) { u := fmt.Sprintf("repos/%v/%v/stats/punch_card", owner, repo) From 588790644eaa34944cbd78d765de63f60de95ad2 Mon Sep 17 00:00:00 2001 From: Carlos Alexandro Becker Date: Fri, 9 Dec 2016 16:29:47 -0200 Subject: [PATCH 05/10] repo forks docs --- github/repos_forks.go | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/github/repos_forks.go b/github/repos_forks.go index 7ef4cb378d1..b36a3f6ceb6 100644 --- a/github/repos_forks.go +++ b/github/repos_forks.go @@ -50,6 +50,12 @@ type RepositoryCreateForkOptions struct { // CreateFork creates a fork of the specified repository. // +// This method might return an *AcceptedError and a status code of +// 202. This is because this is the status that github returns to signify that +// it is now computing creating the fork in a background task. +// A follow up request, after a delay of a second or so, should result +// in a successful request. +// // GitHub API docs: https://developer.github.com/v3/repos/forks/#create-a-fork func (s *RepositoriesService) CreateFork(owner, repo string, opt *RepositoryCreateForkOptions) (*Repository, *Response, error) { u := fmt.Sprintf("repos/%v/%v/forks", owner, repo) From 3468168be7e4298ae458d4620e7ea4e2c209f18a Mon Sep 17 00:00:00 2001 From: Carlos Alexandro Becker Date: Fri, 9 Dec 2016 16:33:01 -0200 Subject: [PATCH 06/10] same formating --- github/repos_stats.go | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/github/repos_stats.go b/github/repos_stats.go index 81818d80c05..418867e91a2 100644 --- a/github/repos_stats.go +++ b/github/repos_stats.go @@ -158,11 +158,10 @@ func (r RepositoryParticipation) String() string { // The array order is oldest week (index 0) to most recent week. // // If this is the first time these statistics are requested for the given -// repository, this method will return an *AcceptedError and a status code -// of 202. This is because this is the status that github returns to -// signify that it is now computing the requested statistics. A follow -// up request, after a delay of a second or so, should result in a -// successful request. +// repository, this method will return an *AcceptedError and a status code of +// 202. This is because this is the status that github returns to signify that +// it is now computing the requested statistics. A follow up request, after a +// delay of a second or so, should result in a successful request. // // GitHub API Docs: https://developer.github.com/v3/repos/statistics/#participation func (s *RepositoriesService) ListParticipation(owner, repo string) (*RepositoryParticipation, *Response, error) { From ba0dc2c5acf595364e4c6d31aae5d49dd908cbe6 Mon Sep 17 00:00:00 2001 From: Carlos Alexandro Becker Date: Fri, 9 Dec 2016 17:03:32 -0200 Subject: [PATCH 07/10] docs --- README.md | 23 ++++++++++++++++++++--- github/doc.go | 15 +++++++++++++++ 2 files changed, 35 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9e4d271bdaf..8b98900267c 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ go-github is a Go client library for accessing the [GitHub API][]. -**Documentation:** [![GoDoc](https://godoc.org/github.com/google/go-github/github?status.svg)](https://godoc.org/github.com/google/go-github/github) -**Mailing List:** [go-github@googlegroups.com](https://groups.google.com/group/go-github) -**Build Status:** [![Build Status](https://travis-ci.org/google/go-github.svg?branch=master)](https://travis-ci.org/google/go-github) +**Documentation:** [![GoDoc](https://godoc.org/github.com/google/go-github/github?status.svg)](https://godoc.org/github.com/google/go-github/github) +**Mailing List:** [go-github@googlegroups.com](https://groups.google.com/group/go-github) +**Build Status:** [![Build Status](https://travis-ci.org/google/go-github.svg?branch=master)](https://travis-ci.org/google/go-github) **Test Coverage:** [![Test Coverage](https://coveralls.io/repos/google/go-github/badge.svg?branch=master)](https://coveralls.io/r/google/go-github?branch=master) ([gocov report](https://drone.io/github.com/google/go-github/files/coverage.html)) go-github requires Go version 1.4 or greater. @@ -99,6 +99,23 @@ if _, ok := err.(*github.RateLimitError); ok { Learn more about GitHub rate limiting at http://developer.github.com/v3/#rate-limiting. +### Accepted status ### + +Some endpoints may return a 202 Accepted status code, meaning that the +information required is not yet ready and was scheduled to be gather in +GitHub side. Methods know to behave like this are documented specifying +this behavior. + +To detect this condition of error, you can check if its type is +`*github.AcceptedError`: + +```go +repos, _, err := client.Repositories.ListContributorsStats(org, repo) +if _, ok := err.(*github.AcceptedError); ok { + log.Println("scheduled on github side") +} +``` + ### Conditional Requests ### The GitHub API has good support for conditional requests which will help diff --git a/github/doc.go b/github/doc.go index 2b61068a134..60cde63bcbc 100644 --- a/github/doc.go +++ b/github/doc.go @@ -86,6 +86,21 @@ To detect an API rate limit error, you can check if its type is *github.RateLimi Learn more about GitHub rate limiting at http://developer.github.com/v3/#rate-limiting. +Accepted status + +Some endpoints may return a 202 Accepted status code, meaning that the +information required is not yet ready and was scheduled to be gather in +GitHub side. Methods know to behave like this are documented specifying +this behavior. + +To detect this condition of error, you can check if its type is +*github.AcceptedError: + + repos, _, err := client.Repositories.ListContributorsStats(org, repo) + if _, ok := err.(*github.AcceptedError); ok { + log.Println("scheduled on github side") + } + Conditional Requests The GitHub API has good support for conditional requests which will help From 50886af7feb995e308e2841e67ac8d1f748664f5 Mon Sep 17 00:00:00 2001 From: Dmitri Shuralyov Date: Sat, 10 Dec 2016 00:26:38 -0500 Subject: [PATCH 08/10] Minor typo fixes in README.md and doc.go. Plus a few other minor changes for improved consistency. --- README.md | 10 +++++----- github/doc.go | 8 ++++---- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 8b98900267c..3685e3561f3 100644 --- a/README.md +++ b/README.md @@ -99,20 +99,20 @@ if _, ok := err.(*github.RateLimitError); ok { Learn more about GitHub rate limiting at http://developer.github.com/v3/#rate-limiting. -### Accepted status ### +### Accepted Status ### Some endpoints may return a 202 Accepted status code, meaning that the -information required is not yet ready and was scheduled to be gather in -GitHub side. Methods know to behave like this are documented specifying +information required is not yet ready and was scheduled to be gathered on +GitHub side. Methods known to behave like this are documented specifying this behavior. To detect this condition of error, you can check if its type is `*github.AcceptedError`: ```go -repos, _, err := client.Repositories.ListContributorsStats(org, repo) +stats, _, err := client.Repositories.ListContributorsStats(org, repo) if _, ok := err.(*github.AcceptedError); ok { - log.Println("scheduled on github side") + log.Println("scheduled on github side") } ``` diff --git a/github/doc.go b/github/doc.go index 60cde63bcbc..b36d9fbde67 100644 --- a/github/doc.go +++ b/github/doc.go @@ -86,17 +86,17 @@ To detect an API rate limit error, you can check if its type is *github.RateLimi Learn more about GitHub rate limiting at http://developer.github.com/v3/#rate-limiting. -Accepted status +Accepted Status Some endpoints may return a 202 Accepted status code, meaning that the -information required is not yet ready and was scheduled to be gather in -GitHub side. Methods know to behave like this are documented specifying +information required is not yet ready and was scheduled to be gathered on +GitHub side. Methods known to behave like this are documented specifying this behavior. To detect this condition of error, you can check if its type is *github.AcceptedError: - repos, _, err := client.Repositories.ListContributorsStats(org, repo) + stats, _, err := client.Repositories.ListContributorsStats(org, repo) if _, ok := err.(*github.AcceptedError); ok { log.Println("scheduled on github side") } From a65a64f7cec4091ba8c6fbff18e605e823be99e1 Mon Sep 17 00:00:00 2001 From: Carlos Alexandro Becker Date: Sat, 10 Dec 2016 12:55:44 -0200 Subject: [PATCH 09/10] adding spaces back --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 3685e3561f3..351c01b4cb6 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,10 @@ go-github is a Go client library for accessing the [GitHub API][]. -**Documentation:** [![GoDoc](https://godoc.org/github.com/google/go-github/github?status.svg)](https://godoc.org/github.com/google/go-github/github) -**Mailing List:** [go-github@googlegroups.com](https://groups.google.com/group/go-github) -**Build Status:** [![Build Status](https://travis-ci.org/google/go-github.svg?branch=master)](https://travis-ci.org/google/go-github) -**Test Coverage:** [![Test Coverage](https://coveralls.io/repos/google/go-github/badge.svg?branch=master)](https://coveralls.io/r/google/go-github?branch=master) ([gocov report](https://drone.io/github.com/google/go-github/files/coverage.html)) +**Documentation:** [![GoDoc](https://godoc.org/github.com/google/go-github/github?status.svg)](https://godoc.org/github.com/google/go-github/github) +**Mailing List:** [go-github@googlegroups.com](https://groups.google.com/group/go-github) +**Build Status:** [![Build Status](https://travis-ci.org/google/go-github.svg?branch=master)](https://travis-ci.org/google/go-github) +**Test Coverage:** [![Test Coverage](https://coveralls.io/repos/google/go-github/badge.svg?branch=master)](https://coveralls.io/r/google/go-github?branch=master) ([gocov report](https://drone.io/github.com/google/go-github/files/coverage.html)) go-github requires Go version 1.4 or greater. From 63045a59e6b8c5954316529651881e65e033b154 Mon Sep 17 00:00:00 2001 From: Carlos Alexandro Becker Date: Sat, 10 Dec 2016 12:57:11 -0200 Subject: [PATCH 10/10] typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 351c01b4cb6..ac219725a76 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ go-github is a Go client library for accessing the [GitHub API][]. **Documentation:** [![GoDoc](https://godoc.org/github.com/google/go-github/github?status.svg)](https://godoc.org/github.com/google/go-github/github) **Mailing List:** [go-github@googlegroups.com](https://groups.google.com/group/go-github) **Build Status:** [![Build Status](https://travis-ci.org/google/go-github.svg?branch=master)](https://travis-ci.org/google/go-github) -**Test Coverage:** [![Test Coverage](https://coveralls.io/repos/google/go-github/badge.svg?branch=master)](https://coveralls.io/r/google/go-github?branch=master) ([gocov report](https://drone.io/github.com/google/go-github/files/coverage.html)) +**Test Coverage:** [![Test Coverage](https://coveralls.io/repos/google/go-github/badge.svg?branch=master)](https://coveralls.io/r/google/go-github?branch=master) ([gocov report](https://drone.io/github.com/google/go-github/files/coverage.html)) go-github requires Go version 1.4 or greater.