feat!: Refactor client constructor to use options pattern

.codecov.yml

@@ -1,7 +1,11 @@
 ignore:
+# ignore examples
+ - "example"
 # ignore auto-generated code
  - "github/github-accessors.go"
 # ignore experimental scrape package
  - "scrape"
+# ignore test
+ - "test"
 # ignore tools
  - "tools"

README.md

@@ -20,7 +20,7 @@ go-github will require the N-1 major release of Go by default.
 
 [support-policy]: https://golang.org/doc/devel/release.html#policy
 
-## Development
+## Development ##
 
 If you're interested in using the [GraphQL API v4][], the recommended library is
 [shurcooL/githubv4][].
@@ -66,7 +66,10 @@ Construct a new GitHub client, then use the various services on the client to
 access different parts of the GitHub API. For example:
 
 ```go
-client := github.NewClient(nil)
+client, err := github.NewClient()
+if err != nil {
+	// Handle error.
+}
 
 // list all organizations for user "willnorris"
 orgs, _, err := client.Organizations.List(context.Background(), "willnorris", nil)
@@ -75,7 +78,10 @@ orgs, _, err := client.Organizations.List(context.Background(), "willnorris", ni
 Some API methods have optional parameters that can be passed. For example:
 
 ```go
-client := github.NewClient(nil)
+client, err := github.NewClient()
+if err != nil {
+	// Handle error.
+}
 
 // list public repositories for org "github"
 opt := &github.RepositoryListByOrgOptions{Type: "public"}
@@ -95,14 +101,23 @@ For more sample code snippets, head over to the
 
 ### Authentication ###
 
-Use the `WithAuthToken` method to configure your client to authenticate using an
+Use the `github.WithAuthToken` options method to configure your client to authenticate using an
 OAuth token (for example, a [personal access token][]). This is what is needed
 for a majority of use cases aside from GitHub Apps.
 
 ```go
-client := github.NewClient(nil).WithAuthToken("... your access token ...")
+client, err := github.NewClient(github.WithAuthToken("... your access token ..."))
+if err != nil {
+	// Handle error.
+}
 ```
 
+To support more advanced use cases; you can use the `github.WithTransport` option to provide a
+custom `http.RoundTripper` that handles authentication for you, or the `github.WithHTTPClient`
+option to provide a custom `http.Client`. As an example; you can use the `oauth2.Transport`
+from the [golang.org/x/oauth2](https://pkg.go.dev/golang.org/x/oauth2) package to handle OAuth
+token refreshing for you.
+
 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.
@@ -146,7 +161,10 @@ func main() {
 	}
 
 	// Use installation transport with client.
-	client := github.NewClient(&http.Client{Transport: itr})
+	client, err := github.NewClient(github.WithTransport(itr))
+	if err != nil {
+ // Handle error.
+	}
 
 	// Use client...
 }
@@ -186,11 +204,14 @@ func main() {
 	// InstallationTokenSource has the mechanism to refresh the token when it expires.
 	httpClient := oauth2.NewClient(context.Background(), installationTokenSource)
 
-	client := github.NewClient(httpClient)
+	client, err := github.NewClient(github.WithHTTPClient(httpClient))
+	if err != nil {
+ // Handle error.
+	}
 }
 ```
 
-*Note*: In order to interact with certain APIs, for example writing a file to a repo, one must generate an installation token
+_Note_: In order to interact with certain APIs, for example writing a file to a repo, one must generate an installation token
 using the installation ID of the GitHub app and authenticate with the OAuth method mentioned above. See the examples.
 
 ### Rate Limiting ###
@@ -296,9 +317,10 @@ import (
 	_ "github.com/bartventer/httpcache/store/memcache" // Register the in-memory backend
 )
 
-client := github.NewClient(
-	httpcache.NewClient("memcache://"),
-).WithAuthToken(os.Getenv("GITHUB_TOKEN"))
+client, err := github.NewClient(github.WithHTTPClient(httpcache.NewClient("memcache://")), github.WithAuthToken(os.Getenv("GITHUB_TOKEN")))
+if err != nil {
+	// Handle error.
+}
 ```
 
 Alternatively, the [bored-engineer/github-conditional-http-transport](https://github.com/bored-engineer/github-conditional-http-transport)
@@ -334,7 +356,10 @@ embedded type of a more specific list options struct (for example
 `github.Response` struct.
 
 ```go
-client := github.NewClient(nil)
+client, err := github.NewClient()
+if err != nil {
+	// Handle error.
+}
 
 opt := &github.RepositoryListByOrgOptions{
 	ListOptions: github.ListOptions{PerPage: 10},
@@ -372,7 +397,10 @@ To handle rate limiting issues, make sure to use a rate-limiting transport.
 To use these methods, simply create an iterator and then range over it, for example:
 
 ```go
-client := github.NewClient(nil)
+client, err := github.NewClient()
+if err != nil {
+	// Handle error.
+}
 var allRepos []*github.Repository
 
 // create an iterator and start looping through all the results
@@ -389,7 +417,10 @@ Alternatively, if you wish to use an external package, there is `enrichman/gh-it
 Its iterator will handle pagination for you, looping through all the available results.
 
 ```go
-client := github.NewClient(nil)
+client, err := github.NewClient()
+if err != nil {
+	// Handle error.
+}
 var allRepos []*github.Repository
 
 // create an iterator and start looping through all the results
@@ -465,12 +496,14 @@ implementing preview features of the GitHub API, we've adopted the following
 versioning policy:
 
 * We increment the **major version** with any incompatible change to
-	non-preview functionality, including changes to the exported Go API surface
-	or behavior of the API.
+ non-preview functionality, including changes to the exported Go API surface
+ or behavior of the API.
+
 * We increment the **minor version** with any backwards-compatible changes to
-	functionality, as well as any changes to preview functionality in the GitHub
-	API. GitHub makes no guarantee about the stability of preview functionality,
-	so neither do we consider it a stable part of the go-github API.
+ functionality, as well as any changes to preview functionality in the GitHub
+ API. GitHub makes no guarantee about the stability of preview functionality,
+ so neither do we consider it a stable part of the go-github API.
+
 * We increment the **patch version** with any backwards-compatible bug fixes.
 
 Preview functionality may take the form of entire methods or simply additional

example/actionpermissions/main.go

@@ -35,7 +35,10 @@ func main() {
  log.Fatal("No owner: owner of repo must be given")
 	}
 	ctx := context.Background()
-	client := github.NewClient(nil).WithAuthToken(token)
+	client, err := github.NewClient(github.WithAuthToken(token))
+	if err != nil {
+ log.Fatal(err)
+	}
 
 	actionsPermissionsRepository, _, err := client.Repositories.GetActionsPermissions(ctx, *owner, *name)
 	if err != nil {

example/auditlogstream/main.go

@@ -157,7 +157,7 @@ func runDelete(args []string) {
 }
 
 func newClient(token, apiURL string) *github.Client {
-	client, err := github.NewClient(nil).WithAuthToken(token).WithEnterpriseURLs(apiURL, apiURL)
+	client, err := github.NewClient(github.WithAuthToken(token), github.WithEnterpriseURLs(apiURL, apiURL))
 	if err != nil {
  log.Fatalf("Error creating GitHub client: %v", err)
 	}

example/basicauth/main.go

@@ -19,6 +19,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"log"
 	"os"
 	"strings"
 
@@ -39,7 +40,10 @@ func main() {
  Password: strings.TrimSpace(string(password)),
 	}
 
-	client := github.NewClient(tp.Client())
+	client, err := github.NewClient(github.WithHTTPClient(tp.Client()))
+	if err != nil {
+ log.Fatalf("error: %v", err)
+	}
 	ctx := context.Background()
 	user, _, err := client.Users.Get(ctx, "")
 
@@ -52,8 +56,7 @@ func main() {
 	}
 
 	if err != nil {
- fmt.Printf("\nerror: %v\n", err)
- return
+ log.Fatalf("error: %v", err)
 	}
 
 	fmt.Printf("\n%v\n", github.Stringify(user))

example/codespaces/newreposecretwithxcrypto/main.go

@@ -73,7 +73,10 @@ func main() {
 	}
 
 	ctx := context.Background()
-	client := github.NewClient(nil).WithAuthToken(token)
+	client, err := github.NewClient(github.WithAuthToken(token))
+	if err != nil {
+ log.Fatal(err)
+	}
 
 	if err := addRepoSecret(ctx, client, *owner, *repo, secretName, secretValue); err != nil {
  log.Fatal(err)

example/codespaces/newusersecretwithxcrypto/main.go

@@ -66,7 +66,10 @@ func main() {
 	}
 
 	ctx := context.Background()
-	client := github.NewClient(nil).WithAuthToken(token)
+	client, err := github.NewClient(github.WithAuthToken(token))
+	if err != nil {
+ log.Fatal(err)
+	}
 
 	if err := addUserSecret(ctx, client, secretName, secretValue, *owner, *repo); err != nil {
  log.Fatal(err)

example/commitpr/main.go

@@ -221,23 +221,27 @@ func main() {
 	if *sourceOwner == "" || *sourceRepo == "" || *commitBranch == "" || *sourceFiles == "" || *authorName == "" || *authorEmail == "" {
  log.Fatal("You need to specify a non-empty value for the flags `-source-owner`, `-source-repo`, `-commit-branch`, `-files`, `-author-name` and `-author-email`")
 	}
-	client = github.NewClient(nil).WithAuthToken(token)
+	c, err := github.NewClient(github.WithAuthToken(token))
+	if err != nil {
+ log.Fatal(err)
+	}
+	client = c
 
 	ref, err := getRef()
 	if err != nil {
- log.Fatalf("Unable to get/create the commit reference: %v\n", err)
+ log.Fatalf("Unable to get/create the commit reference: %v", err)
 	}
 	if ref == nil {
  log.Fatal("No error where returned but the reference is nil")
 	}
 
 	tree, err := getTree(ref)
 	if err != nil {
- log.Fatalf("Unable to create the tree based on the provided files: %v\n", err)
+ log.Fatalf("Unable to create the tree based on the provided files: %v", err)
 	}
 
 	if err := pushCommit(ref, tree); err != nil {
- log.Fatalf("Unable to create the commit: %v\n", err)
+ log.Fatalf("Unable to create the commit: %v", err)
 	}
 
 	if err := createPR(); err != nil {

example/contents/main.go

@@ -16,6 +16,7 @@ import (
 	"context"
 	"fmt"
 	"io"
+	"log"
 	"os"
 	"path/filepath"
 	"strings"
@@ -50,25 +51,25 @@ func main() {
 
 	fmt.Printf("\nDownloading %v/%v/%v at ref %v to %v...\n", owner, repo, repoPath, ref, outputPath)
 
-	client := github.NewClient(nil)
+	client, err := github.NewClient()
+	if err != nil {
+ log.Fatalf("Error creating GitHub client: %v", err)
+	}
 
 	rc, _, err := client.Repositories.DownloadContents(context.Background(), owner, repo, repoPath, &github.RepositoryContentGetOptions{Ref: ref})
 	if err != nil {
- fmt.Printf("Error: %v\n", err)
- os.Exit(1)
+ log.Fatalf("Error downloading contents: %v", err)
 	}
 	defer rc.Close()
 
 	f, err := os.Create(outputPath) //#nosec G703 -- path is validated above
 	if err != nil {
- fmt.Printf("Error: %v\n", err)
- os.Exit(1)
+ log.Fatalf("Error creating output file: %v", err)
 	}
 	defer f.Close()
 
 	if _, err := io.Copy(f, rc); err != nil {
- fmt.Printf("Error: %v\n", err)
- os.Exit(1)
+ log.Fatalf("Error writing to output file: %v", err)
 	}
 
 	fmt.Println("Download completed.")

example/listenvironments/main.go

@@ -31,7 +31,10 @@ func main() {
 	}
 
 	ctx := context.Background()
-	client := github.NewClient(nil).WithAuthToken(token)
+	client, err := github.NewClient(github.WithAuthToken(token))
+	if err != nil {
+ log.Fatal(err)
+	}
 
 	expectedPageSize := 2
 

example/migrations/main.go

@@ -11,13 +11,17 @@ package main
 import (
 	"context"
 	"fmt"
+	"log"
 
 	"github.com/google/go-github/v86/github"
 )
 
 func fetchAllUserMigrations() ([]*github.UserMigration, error) {
 	ctx := context.Background()
-	client := github.NewClient(nil).WithAuthToken("<GITHUB_AUTH_TOKEN>")
+	client, err := github.NewClient(github.WithAuthToken("<GITHUB_AUTH_TOKEN>"))
+	if err != nil {
+ return nil, err
+	}
 
 	migrations, _, err := client.Migrations.ListUserMigrations(ctx, &github.ListOptions{Page: 1})
 	return migrations, err
@@ -26,8 +30,7 @@ func fetchAllUserMigrations() ([]*github.UserMigration, error) {
 func main() {
 	migrations, err := fetchAllUserMigrations()
 	if err != nil {
- fmt.Printf("Error %v\n", err)
- return
+ log.Fatalf("Error: %v", err)
 	}
 
 	for i, m := range migrations {