go dep

Migrated from plain /vendor to go dep

vendor/github.com/google/go-github/github/doc.go

@@ -6,23 +6,29 @@
 /*
 Package github provides a client for using the GitHub API.
 
+Usage:
+
+	import "github.com/google/go-github/github"
+
 Construct a new GitHub client, then use the various services on the client to
 access different parts of the GitHub API. For example:
 
 	client := github.NewClient(nil)
 
 	// list all organizations for user "willnorris"
-	orgs, _, err := client.Organizations.List("willnorris", nil)
+	orgs, _, err := client.Organizations.List(ctx, "willnorris", nil)
 
-Set optional parameters for an API method by passing an Options object.
+Some API methods have optional parameters that can be passed. For example:
 
-	// list recently updated repositories for org "github"
-	opt := &github.RepositoryListByOrgOptions{Sort: "updated"}
-	repos, _, err := client.Repositories.ListByOrg("github", opt)
+	client := github.NewClient(nil)
+
+	// list public repositories for org "github"
+	opt := &github.RepositoryListByOrgOptions{Type: "public"}
+	repos, _, err := client.Repositories.ListByOrg(ctx, "github", opt)
 
 The services of a client divide the API into logical chunks and correspond to
 the structure of the GitHub API documentation at
-http://developer.github.com/v3/.
+https://developer.github.com/v3/.
 
 Authentication
 
@@ -36,54 +42,92 @@ use it with the oauth2 library using:
 	import "golang.org/x/oauth2"
 
 	func main() {
+		ctx := context.Background()
 		ts := oauth2.StaticTokenSource(
 			&oauth2.Token{AccessToken: "... your access token ..."},
 		)
-		tc := oauth2.NewClient(oauth2.NoContext, ts)
+		tc := oauth2.NewClient(ctx, ts)
 
 		client := github.NewClient(tc)
 
 		// list all repositories for the authenticated user
-		repos, _, err := client.Repositories.List("", nil)
+		repos, _, err := client.Repositories.List(ctx, "", nil)
 	}
 
 Note that when using an authenticated Client, all calls made by the client will
 include the specified OAuth token. Therefore, authenticated clients should
 almost never be shared between different users.
 
+See the oauth2 docs for complete instructions on using that library.
+
+For API methods that require HTTP Basic Authentication, use the
+BasicAuthTransport.
+
+GitHub Apps authentication can be provided by the
+https://github.com/bradleyfalzon/ghinstallation package.
+
+	import "github.com/bradleyfalzon/ghinstallation"
+
+	func main() {
+		// Wrap the shared transport for use with the integration ID 1 authenticating with installation ID 99.
+		itr, err := ghinstallation.NewKeyFromFile(http.DefaultTransport, 1, 99, "2016-10-19.private-key.pem")
+		if err != nil {
+			// Handle error.
+		}
+
+		// Use installation transport with client
+		client := github.NewClient(&http.Client{Transport: itr})
+
+		// Use client...
+	}
+
 Rate Limiting
 
-GitHub imposes a rate limit on all API clients.  Unauthenticated clients are
+GitHub imposes a rate limit on all API clients. Unauthenticated clients are
 limited to 60 requests per hour, while authenticated clients can make up to
-5,000 requests per hour.  To receive the higher rate limit when making calls
-that are not issued on behalf of a user, use the
-UnauthenticatedRateLimitedTransport.
+5,000 requests per hour. The Search API has a custom rate limit. Unauthenticated
+clients are limited to 10 requests per minute, while authenticated clients
+can make up to 30 requests per minute. To receive the higher rate limit when
+making calls that are not issued on behalf of a user,
+use UnauthenticatedRateLimitedTransport.
 
-The Rate method on a client returns the rate limit information based on the most
-recent API call.  This is updated on every call, but may be out of date if it's
-been some time since the last API call and other clients have made subsequent
-requests since then.  You can always call RateLimits() directly to get the most
-up-to-date rate limit data for the client.
+The returned Response.Rate value contains the rate limit information
+from the most recent API call. If a recent enough response isn't
+available, you can use RateLimits to fetch the most up-to-date rate
+limit data for the client.
 
 To detect an API rate limit error, you can check if its type is *github.RateLimitError:
 
-	repos, _, err := client.Repositories.List("", nil)
+	repos, _, err := client.Repositories.List(ctx, "", nil)
 	if _, ok := err.(*github.RateLimitError); ok {
 		log.Println("hit rate limit")
 	}
 
 Learn more about GitHub rate limiting at
-http://developer.github.com/v3/#rate-limiting.
+https://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 gathered on
+the 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:
+
+	stats, _, err := client.Repositories.ListContributorsStats(ctx, 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
 prevent you from burning through your rate limit, as well as help speed up your
-application.  go-github does not handle conditional requests directly, but is
-instead designed to work with a caching http.Transport.  We recommend using
-https://github.com/gregjones/httpcache, which can be used in conjunction with
-https://github.com/sourcegraph/apiproxy to provide additional flexibility and
-control of caching rules.
+application. go-github does not handle conditional requests directly, but is
+instead designed to work with a caching http.Transport. We recommend using
+https://github.com/gregjones/httpcache for that.
 
 Learn more about GitHub conditional requests at
 https://developer.github.com/v3/#conditional-requests.
@@ -93,24 +137,27 @@ Creating and Updating Resources
 All structs for GitHub resources use pointer values for all non-repeated fields.
 This allows distinguishing between unset fields and those set to a zero-value.
 Helper functions have been provided to easily create these pointers for string,
-bool, and int values.  For example:
+bool, and int values. For example:
 
 	// create a new private repository named "foo"
 	repo := &github.Repository{
 		Name:    github.String("foo"),
 		Private: github.Bool(true),
 	}
-	client.Repositories.Create("", repo)
+	client.Repositories.Create(ctx, "", repo)
 
 Users who have worked with protocol buffers should find this pattern familiar.
 
 Pagination
 
-All requests for resource collections (repos, pull requests, issues, etc)
+All requests for resource collections (repos, pull requests, issues, etc.)
 support pagination. Pagination options are described in the
-ListOptions struct and passed to the list methods directly or as an
+github.ListOptions struct and passed to the list methods directly or as an
 embedded type of a more specific list options struct (for example
-PullRequestListOptions).  Pages information is available via Response struct.
+github.PullRequestListOptions). Pages information is available via the
+github.Response struct.
+
+	client := github.NewClient(nil)
 
 	opt := &github.RepositoryListByOrgOptions{
 		ListOptions: github.ListOptions{PerPage: 10},
@@ -118,7 +165,7 @@ PullRequestListOptions).  Pages information is available via Response struct.
 	// get all pages of results
 	var allRepos []*github.Repository
 	for {
-		repos, resp, err := client.Repositories.ListByOrg("github", opt)
+		repos, resp, err := client.Repositories.ListByOrg(ctx, "github", opt)
 		if err != nil {
 			return err
 		}
@@ -126,8 +173,19 @@ PullRequestListOptions).  Pages information is available via Response struct.
 		if resp.NextPage == 0 {
 			break
 		}
-		opt.ListOptions.Page = resp.NextPage
+		opt.Page = resp.NextPage
 	}
 
+Google App Engine
+
+Go on App Engine Classic (which as of this writing uses Go 1.6) can not use
+the "context" import and still relies on "golang.org/x/net/context".
+As a result, if you wish to continue to use "go-github" on App Engine Classic,
+you will need to rewrite all the "context" imports using the following command:
+
+	gofmt -w -r '"context" -> "golang.org/x/net/context"' *.go
+
+See "with_appengine.go" for more details.
+
 */
 package github