diff --git a/README.md b/README.md index 6f5c7aaea7..585790b758 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # go-github # [![go-github release (latest SemVer)](https://img.shields.io/github/v/release/google/go-github?sort=semver)](https://github.com/google/go-github/releases) -[![GoDoc](https://img.shields.io/static/v1?label=godoc&message=reference&color=blue)](https://pkg.go.dev/github.com/google/go-github/v65/github) +[![Go Reference](https://img.shields.io/static/v1?label=godoc&message=reference&color=blue)](https://pkg.go.dev/github.com/google/go-github/v65/github) [![Test Status](https://github.com/google/go-github/workflows/tests/badge.svg)](https://github.com/google/go-github/actions?query=workflow%3Atests) [![Test Coverage](https://codecov.io/gh/google/go-github/branch/master/graph/badge.svg)](https://codecov.io/gh/google/go-github) [![Discuss at go-github@googlegroups.com](https://img.shields.io/badge/discuss-go--github%40googlegroups.com-blue.svg)](https://groups.google.com/group/go-github) @@ -9,7 +9,7 @@ go-github is a Go client library for accessing the [GitHub API v3][]. -Currently, **go-github requires Go version 1.13 or greater**. go-github tracks +Currently, **go-github tests against Go version 1.22 and greater**. go-github tracks [Go's version support policy][support-policy]. We do our best not to break older versions of Go if we don't have to, but due to tooling constraints, we don't always test older versions. @@ -71,10 +71,9 @@ repos, _, err := client.Repositories.ListByOrg(context.Background(), "github", o ``` The services of a client divide the API into logical chunks and correspond to -the structure of the GitHub API documentation at -https://docs.github.com/en/rest . +the structure of the [GitHub API documentation](https://docs.github.com/en/rest). -NOTE: Using the [context](https://godoc.org/context) package, one can easily +NOTE: Using the [context](https://pkg.go.dev/context) package, one can easily pass cancelation signals and deadlines to various services of the client for handling a request. In case there is no context available, then `context.Background()` can be used as a starting point. @@ -97,11 +96,12 @@ include the specified OAuth token. Therefore, authenticated clients should almost never be shared between different users. For API methods that require HTTP Basic Authentication, use the -[`BasicAuthTransport`](https://godoc.org/github.com/google/go-github/github#BasicAuthTransport). +[`BasicAuthTransport`](https://pkg.go.dev/github.com/google/go-github/github#BasicAuthTransport). #### As a GitHub App #### -GitHub Apps authentication can be provided by different pkgs like [ghinstallation](https://github.com/bradleyfalzon/ghinstallation) or [go-githubauth](https://github.com/jferrl/go-githubauth). +GitHub Apps authentication can be provided by different pkgs like [bradleyfalzon/ghinstallation](https://github.com/bradleyfalzon/ghinstallation) +or [jferrl/go-githubauth](https://github.com/jferrl/go-githubauth). > **Note**: Most endpoints (ex. [`GET /rate_limit`]) require access token authentication > while a few others (ex. [`GET /app/hook/deliveries`]) require [JWT] authentication. @@ -148,33 +148,33 @@ Other example using `go-githubauth`: package main import ( - "context" - "fmt" - "os" - "strconv" - - "github.com/google/go-github/v65/github" - "github.com/jferrl/go-githubauth" - "golang.org/x/oauth2" + "context" + "fmt" + "os" + "strconv" + + "github.com/google/go-github/v65/github" + "github.com/jferrl/go-githubauth" + "golang.org/x/oauth2" ) func main() { - privateKey := []byte(os.Getenv("GITHUB_APP_PRIVATE_KEY")) + privateKey := []byte(os.Getenv("GITHUB_APP_PRIVATE_KEY")) - appTokenSource, err := githubauth.NewApplicationTokenSource(1112, privateKey) - if err != nil { - fmt.Println("Error creating application token source:", err) - return - } + appTokenSource, err := githubauth.NewApplicationTokenSource(1112, privateKey) + if err != nil { + fmt.Println("Error creating application token source:", err) + return + } - installationTokenSource := githubauth.NewInstallationTokenSource(1113, appTokenSource) + installationTokenSource := githubauth.NewInstallationTokenSource(1113, appTokenSource) - // oauth2.NewClient uses oauth2.ReuseTokenSource to reuse the token until it expires. - // The token will be automatically refreshed when it expires. - // InstallationTokenSource has the mechanism to refresh the token when it expires. - httpClient := oauth2.NewClient(context.Background(), installationTokenSource) + // oauth2.NewClient uses oauth2.ReuseTokenSource to reuse the token until it expires. + // The token will be automatically refreshed when it expires. + // InstallationTokenSource has the mechanism to refresh the token when it expires. + httpClient := oauth2.NewClient(context.Background(), installationTokenSource) - client := github.NewClient(httpClient) + client := github.NewClient(httpClient) } ``` @@ -205,8 +205,8 @@ if _, ok := err.(*github.RateLimitError); ok { } ``` -Learn more about GitHub rate limiting at -https://docs.github.com/en/rest/rate-limit . +Learn more about GitHub rate limiting in +["REST API endpoints for rate limits"](https://docs.github.com/en/rest/rate-limit). In addition to these rate limits, GitHub imposes a secondary rate limit on all API clients. This rate limit prevents clients from making too many concurrent requests. @@ -226,11 +226,11 @@ Alternatively, you can block until the rate limit is reset by using the `context repos, _, err := client.Repositories.List(context.WithValue(ctx, github.SleepUntilPrimaryRateLimitResetWhenRateLimited, true), "", nil) ``` -You can use [go-github-ratelimit](https://github.com/gofri/go-github-ratelimit) to handle +You can use [gofri/go-github-ratelimit](https://github.com/gofri/go-github-ratelimit) to handle secondary rate limit sleep-and-retry for you. -Learn more about GitHub secondary rate limiting at -https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28#about-secondary-rate-limits . +Learn more about GitHub secondary rate limiting in +["About secondary rate limits"](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28#about-secondary-rate-limits). ### Accepted Status ### @@ -255,7 +255,7 @@ 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 for that. For example: +[gregjones/httpcache](https://github.com/gregjones/httpcache) for that. For example: ```go import "github.com/gregjones/httpcache" @@ -265,8 +265,8 @@ import "github.com/gregjones/httpcache" ).WithAuthToken(os.Getenv("GITHUB_TOKEN")) ``` -Learn more about GitHub conditional requests at -https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api?apiVersion=2022-11-28#use-conditional-requests-if-appropriate +Learn more about GitHub conditional requests in +["Use conditional requests if appropriate"](https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api?apiVersion=2022-11-28#use-conditional-requests-if-appropriate). ### Creating and Updating Resources ### @@ -316,7 +316,7 @@ for { } ``` -#### Iterators (**experimental**) +#### Iterators (**experimental**) #### Go v1.23 introduces the new `iter` package. @@ -367,7 +367,7 @@ For complete usage of go-github, see the full [package docs][]. [GitHub webhook events]: https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads [cbrgm/githubevents]: https://github.com/cbrgm/githubevents -### Testing code that uses `go-github` +### Testing code that uses `go-github` ### The repo [migueleliasweb/go-github-mock](https://github.com/migueleliasweb/go-github-mock) provides a way to mock responses. Check the repo for more details. @@ -376,6 +376,7 @@ The repo [migueleliasweb/go-github-mock](https://github.com/migueleliasweb/go-gi You can run integration tests from the `test` directory. See the integration tests [README](test/README.md). ## Contributing ## + I would like to cover the entire GitHub API and contributions are of course always welcome. The calling pattern is pretty well established, so adding new methods is relatively straightforward. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details.