docs(api): clarify redirect method-rewriting in comments

Note that Go's default redirect policy rewrites any non-GET/HEAD method (not just DELETE) to GET on 301/302/303, and document why repo delete opts out of following redirects to avoid a phantom success. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: eb7763a9-2086-461a-91a4-86ea4a2d078d
williammartin · Sep 2, 2026 · Aug 7, 2026 · Aug 7, 2026 · Aug 7, 2026 · Aug 7, 2026
commit 97fcb734c46313f952e205ea0f93e011cd28e59e
@@ -73,9 +73,9 @@ func WithHeader(name, value string) RequestOption {
 // WithoutFollowingRedirects stops the request from following redirects. When a redirect is
 // encountered, the request fails with an HTTPError carrying the redirect status code and headers
 // rather than following the redirect. This matters for requests where following a redirect
-// silently changes the meaning of the request: Go's default policy converts a DELETE into a GET
-// when it follows a 301, so a caller deleting a renamed resource would receive a success response
-// while having deleted nothing.
+// silently changes the meaning of the request: Go's default policy converts methods other than
+// GET or HEAD (e.g. DELETE) into a GET when it follows a 301/302/303, so a caller deleting a renamed
+// resource would receive a success response while having deleted nothing.
 //
 // This option applies only to the REST request surface (Request and RequestWithContext). It has no
 // effect on GraphQL methods, which do not encounter redirects in practice.

@@ -355,8 +355,8 @@ func TestHTTPHeaders(t *testing.T) {
 // TestWithoutFollowingRedirects verifies that WithoutFollowingRedirects stops the request at the
 // redirect and surfaces an HTTPError rather than following through. It also proves the redirect is
 // not followed by recording every method the transport sees: without the option the transport would
-// receive a second call (GET, because Go demotes DELETE to GET on a 301 follow); with it, only the
-// original DELETE arrives.
+// receive a second call (GET, because Go demotes non-GET/HEAD to GET on a 301/302/303
+// follow); with it, only the original DELETE arrives.
 //
 // go-gh's RequestWithContext converts any non-2xx response - including 3xx - into an HTTPError.
 // When http.ErrUseLastResponse stops a redirect the client returns the 3xx response with a nil

@@ -14,6 +14,12 @@ func deleteRepo(httpClient *http.Client, repo ghrepo.Interface) error {
 		return err
 	}
 
+	// If the repo is renamed (and we're using the old name), the API will return
+	// an HTTP 307 (temporary redirect), which is a METHOD-preserving redirection.
+	// That is, upon receiving a 307, the HTTP client will repeat the same HTTP
+	// method (in this case, DELETE) but against the new location. We don't want
+	// such an implicit behaviour, so we pass the `api.WithoutFollowingRedirects`
+	// to make sure an error is returned.
 	resp, err := api.NewClientFromHTTP(httpClient).Request(repo.RepoHost(), http.MethodDelete, p.String(), nil,
 		api.WithEndpointScopes("delete_repo"),
 		api.WithoutFollowingRedirects(),