Add support for the repository transfer API #788
Conversation
This API allows for the transfer of one GitHub repository to another user or organization. Announcement: https://developer.github.com/changes/2017-11-09-repository-transfer-api-preview/. GitHub API Docs: https://developer.github.com/v3/repos/#transfer-a-repository. Fixes #777.
googlebot
added
the
cla: yes
There was a problem hiding this comment.
Thank you, @juliaferraioli!
LGTM.
@shurcooL and/or @elliott-beach can review, then @shurcooL can merge.
github/repos.go
Outdated
|
|
||
| // TransferRequest represents a request to transfer a repository. | ||
| type TransferRequest struct { | ||
| NewOwner string `json:"new_owner,omitempty"` |
There was a problem hiding this comment.
According to GitHub API docs, new_owner is required, so I don't think omitempty is appropriate here.
There was a problem hiding this comment.
Excellent catch. Fixed.
github/repos.go
Outdated
| // in a successful request. | ||
| // | ||
| // GitHub API docs: https://developer.github.com/v3/repos/#transfer-a-repository | ||
| func (s *RepositoriesService) Transfer(ctx context.Context, owner, repo string, transfer *TransferRequest) (*Repository, *Response, error) { |
There was a problem hiding this comment.
Why is transfer a *TransferRequest pointer rather than value?
That means user can pass nil, but that wouldn't be meaningful, would it?
There was a problem hiding this comment.
I understand your point here. And while I tend to agree, there's precedent for this approach even in repos.create being passed a pointer to a Repo. I didn't want to introduce code that broke with that model.
Thoughts?
There was a problem hiding this comment.
there's precedent for this approach even in repos.create being passed a pointer to a Repo. I didn't want to introduce code that broke with that model.
I see. However, that API decision was made 5 years ago, and is not very representative of the best practices regarding API decisions this repo has evolved toward since that time.
In fact, we've ran into possible panics in the library caused due to such parameters being passed as pointers in situations where nil values made no sense. We dealt with that in #531 and #539, by adding if param == nil { return errors.New(...) } guards.
We went that route because it was less disruptive than breaking an API for a very minor improvement. Given two equivalent choices, we prefer consistency.
However, in this case, it's a new API, so we can go with the best API design we can come up with. Using a pointer isn't meaningful and doesn't add value (does it?), but it create a liability for dealing with users potentially passing nil values.
I understand your point about wanting to be consistent with existing code, but in this case, I don't think the consistency argument applies, because using a pointer has tangible downsides compared to using a value. They're not equivalent choices. When adding new APIs to this library, we try to follow the best known practices, and we sometimes even break APIs of preview endpoints when improvements are discovered.
If you want to see more recent precedent, see #773 which came up during review of #771. The original version started by using pointers, but we came to agreement that value parameters were better.
(One could argue that TransferRequest contains just 2 fields that could be inlined into the method signature. However, I think using a dedicated struct for it as you've done makes sense, because it maps more closely to GitHub API as documented, and will be easy to update should GitHub add extra fields to that input object.)
What do you think?
There was a problem hiding this comment.
That sounds reasonable to me. Thanks for the thorough background! I'll go ahead and work on the updates today.
I had thought about your parenthetical initially, but decided against it for exactly the reasons you enumerated.
This API allows for the transfer of one GitHub repository to another user or organization. Announcement: https://developer.github.com/changes/2017-11-09-repository-transfer-api-preview/. GitHub API docs: https://developer.github.com/v3/repos/#transfer-a-repository. Fixes google#777.
| // TransferRequest represents a request to transfer a repository. | ||
| type TransferRequest struct { | ||
| NewOwner string `json:"new_owner"` | ||
| TeamID []int `json:"team_id,omitempty"` |
There was a problem hiding this comment.
I just noticed now, I think the JSON name team_id should've been team_ids, isn't that right?
From https://developer.github.com/v3/repos/#transfer-a-repository:
Unless GitHub API documentation is incorrect. I don't have any evidence suggesting that.
(FWIW, https://developer.github.com/v3/orgs/members/#create-organization-invitation also uses team_ids.)
There was a problem hiding this comment.
Yikes! Nice catch indeed. I can prepare a pr tomorrow (unless you already have one). I'm afk for the rest of tonight.
There was a problem hiding this comment.
Thank you, @juliaferraioli! No rush... this is not urgent.
According to GitHub API docs at https://developer.github.com/v3/repos/#transfer-a-repository, the field name should be "team_ids". This change updates it to match. Fixes #946. Updates #788.
According to GitHub API docs at https://developer.github.com/v3/repos/#transfer-a-repository, the field name should be "team_ids". This change updates it to match. Fixes google#946. Updates google#788.
According to GitHub API docs at https://developer.github.com/v3/repos/#transfer-a-repository, the field name should be "team_ids". This change updates it to match. Fixes google#946. Updates google#788.
As announced here:
https://developer.github.com/changes/2017-11-09-repository-transfer-api-preview/
And detailed here:
https://developer.github.com/v3/repos/#transfer-a-repository
Fixes #777