Add ListPendingOrgInvitations method and Invitation.Inviter field. by varadarajana · Pull Request #527 · google/go-github

varadarajana · 2017-01-21T06:29:32Z

This change is made to incorporate changes to GitHub for Issue #514
Here I have tried to change the test case to include the entire response.
I have not been able to compare time.Time field in Invitation struct. I need to work on the Date time conversions.

Resolves #514.

varadarajana · 2017-01-21T06:40:00Z

@shurcooL @gmlewis Can you please review this?

varadarajana · 2017-01-21T09:20:37Z

The golang documentation of time, requires structs to access as time.Time and not *time.Time. So changed it as it.
The URL https://developer.github.com/v3/orgs/teams/#list-pending-team-invitations does not provide correct date format I think, it is not consistent with other API in the documentation. I have changed the return JSON to the type consistent and mentioned in the documentation of GitHub.
https://developer.github.com/v3/ states dates to be
All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

varadarajana · 2017-01-21T11:24:44Z

I have now added support for Orgs List Members Invitation also. Now this contains both List Members as well as Team Invitations.

dmitshur

Looks good. I've reviewed and left first pass comments.

dmitshur · 2017-01-26T21:28:44Z

github/orgs_members.go

+//ListPendingOrgInvitations returns a list of contains a role field which refers to the
+//Organization Invitation role and will be one of the following values:
+//direct_member, admin, billing_manager, hiring_manager, or reinstate.
+//If the invitee is not a GitHub member, the login field in the return hash will be null.


Don't forget to include a space between the text and //.

Rationale: https://dmitri.shuralyov.com/idiomatic-go#comments-for-humans-always-have-a-single-space-after-the-slashes

This documentation is hard to read and strangely detailed (it refers to specifics of the returned values inside Invitation struct).

We should either omit it altogether, just say // ListPendingOrgInvitations returns a list of pending organization invitations., or update it to be specific to go-github. The returned thing is []Invitation, a slice of invitations, not a hash. There's no null, it's nil. Etc.

It would make sense to me to move the documentation of role to the Invitation struct itself, not here. Unless it's specific to this method, is it?

@shurcooL Yes, this has been changed.

dmitshur · 2017-01-26T21:29:10Z

github/orgs_members.go

+//If the invitee is not a GitHub member, the login field in the return hash will be null.
+//
+// GitHub API docs:
+// https://developer.github.com/v3/orgs/members/#list-pending-organization-invitations


There's no benefit in putting the long URL on a new line. We're not hard-limited to the width of a punch card, it's fine to keep it on the same line.

@shurcooL this is done.

dmitshur · 2017-01-26T21:41:00Z

github/orgs_teams.go

+	Role  *string `json:"role,omitempty"`
+	//golang documentation states
+	//Programs using times should typically store and pass them as values, not pointers.
+	//That is, time variables and struct fields should be of type time.Time, not *time.Time


This comment shouldn't be here as part of the final PR.

I will respond to it.

While it's true that it's fine to use time.Time as a value, the reason we're using it as a point here is because of JSON encoding. We want to be able to tell (sometimes) that a field is absent by checking if its value is nil.

So, we want to keep CreatedAt as a pointer to *time.Time. If you want to discuss this further, I suggest opening a new issue, because it's outside of the scope of this PR.

Edit: I missed your #527 (comment), let me look into that. I'll update this comment afterwards.

Okay, question, have you considered using *Timestamp here instead of *time.Time?

Can you be more specific about the problem you're seeing with *time.Time as is?

@shurcooL in fact this time i tried pointer to time.Time, and it worked. i assigned it to a variable and then passed its address.

dmitshur · 2017-01-26T21:41:31Z

github/orgs_teams.go

 	return Stringify(i)
 }

+// Inviter represents the entity introduced in team and org invitations


A period is missing at the end of this sentence.

Also, you can write the full word "organization", there's no need for a short form here.

@shurcooL this is done.

dmitshur · 2017-01-28T23:40:20Z

github/orgs_members_test.go

+		t.Errorf("Organizations.ListPendingOrgInvitations returned error: %v", err)
+	}
+
+	tm := time.Date(2017, 01, 21, 0, 0, 0, 0, time.UTC)


Nitpick, what does tm mean? It doesn't seem to be short for anything, and I don't think it's an acronym. Is it meant to stand for "time" except without letters i and e?

I'd suggest naming it something more clear. Just createdAt could work well.

@shurcooL yes, tm was not proper, i have set it as createdAt

dmitshur · 2017-01-28T23:44:46Z

github/orgs_teams.go


-// Invitation represents a team member's inviation status
+// Invitation represents a team member's invitation status.
+// Role can be one of the values - direct_member, admin, billing_manager, hiring_manager, or reinstate.


// Role can be one of the values ...

Move that comment near Role field:

// Role can be one of ... Role *string `json:"role,omitempty"`

See

go-github/github/migrations_source_import.go

Lines 14 to 15 in c9c37fd

// The originating VCS type. Can be one of 'subversion', 'git',

// 'mercurial', or 'tfvc'. Without this parameter, the import job will

for an example.

@shurcooL yes this is done.

dmitshur · 2017-01-28T23:45:29Z

github/orgs_teams.go

+	Events_url          *string `json:"events_url,omitempty"`
+	Received_events_url *string `json:"received_events_url,omitempty"`
+	Type                *string `json:"type,omitempty"`
+	Site_admin          bool    `json:"site_admin,omitempty"`


Site_admin should also be a pointer, i.e., *bool.

Most of these variables need to be renamed to follow Go style.

See:

https://github.com/golang/go/wiki/CodeReviewComments#mixed-caps

https://github.com/golang/go/wiki/CodeReviewComments#initialisms

So, it should be SiteAdmin, not Site_admin. URL, not Url. HTMLURL, not Html_url, etc.

@shurcooL this is also done now.

dmitshur

Thanks for addressing previous feedback, that part looks great.

I've spotted another simplification we can make. The new Inviter struct can be replaced by an existing one. See inline comments.

dmitshur · 2017-01-29T19:37:06Z

github/orgs_teams.go

+	ReceivedEventsURL *string `json:"received_events_url,omitempty"`
+	Type              *string `json:"type,omitempty"`
+	SiteAdmin         *bool   `json:"site_admin,omitempty"`
+}


I think this new struct is just a subset of User. I think we can and should use User instead of creating a new struct. So you can delete this struct.

@shurcooL yes, thank you, i missed it. I have corrected it and checked in.

dmitshur · 2017-01-29T19:38:50Z

github/orgs_teams.go

+	// Role can be one of the values - direct_member, admin, billing_manager, hiring_manager, or reinstate.
 	Role      *string    `json:"role,omitempty"`
 	CreatedAt *time.Time `json:"created_at,omitempty"`
+	Inviter   *Inviter   `json:"inviter,omitempty"`


Use User instead of Inviter here:

Inviter *User `json:"inviter,omitempty"`

See here for precedent:

https://github.com/google/go-github/blob/c9c37fd6/github/repos_invitations.go#L15

@shurcooL yes, thank you, i missed it. I have corrected it and checked in.

dmitshur

LGTM. Thanks @varadarajana.

@gmlewis, mind looking it over before we merge?

dmitshur · 2017-01-30T19:16:07Z

github/orgs_members.go

+// ListPendingOrgInvitations returns a list of pending invitations.
+//
+// GitHub API docs: https://developer.github.com/v3/orgs/members/#list-pending-organization-invitations
+func (s *OrganizationsService) ListPendingOrgInvitations(org int, opt *ListOptions) ([]*Invitation, *Response, error) {


One more thought. Should we spell out the entire word "Organization"? I don't think we shorten "Organization" to "Org" anywhere else. E.g.:

https://godoc.org/github.com/google/go-github/github#ActivityService.ListEventsForOrganization

Correct me if I'm wrong, but an invite only relates to Organizations anyway, right?
Also, this is the OrganizationsService, so I'm thinking that a more idiomatic-Go-way to handle this (specifically to reduce stutter) would be to drop the Org entirely... so when a client uses the call, it would look like:

... := c.Organizations.ListPendingInvitations(...)

Thoughts?

Good catch, that's even better!

I don't think we shorten "Organization" to "Org" anywhere else.

Well, I just found a counterexample of that:

https://github.com/google/go-github/blob/4baf08e3bbebb0f/github/orgs_members.go#L178-L181

Yeah... I don't like that as much. ☹️
Your call, @shurcooL as a tie-breaker. 😃

Hmm. Looking at the methods of OrganizationsService more closely, it seems there's many, many uses of Org. So I'm afraid it might make sense to stay consistent with that and keep this as is.

It seems valuable to keep Org because it makes it more clear that the pending invitation applies to org, rather than team (which also exists).

Notice there's RemoveOrgMembership and RemoveTeamMembership.

After this PR, there will be ListPendingOrgInvitations and ListPendingTeamInvitations, which is very consistent.

gmlewis

This is looking great, @varadarajana... thank you!
Just a few minor comments if you don't mind.

gmlewis · 2017-01-31T05:59:01Z

github/orgs_members.go

+// ListPendingOrgInvitations returns a list of pending invitations.
+//
+// GitHub API docs: https://developer.github.com/v3/orgs/members/#list-pending-organization-invitations
+func (s *OrganizationsService) ListPendingOrgInvitations(org int, opt *ListOptions) ([]*Invitation, *Response, error) {


Correct me if I'm wrong, but an invite only relates to Organizations anyway, right?
Also, this is the OrganizationsService, so I'm thinking that a more idiomatic-Go-way to handle this (specifically to reduce stutter) would be to drop the Org entirely... so when a client uses the call, it would look like:

... := c.Organizations.ListPendingInvitations(...)

Thoughts?

gmlewis · 2017-01-31T06:03:23Z

github/orgs_members.go

+	// TODO: remove custom Accept header when this API fully launches.
+	req.Header.Set("Accept", mediaTypeOrgMembershipPreview)
+
+	pendingInvitations := new([]*Invitation)


Just for the record, I don't like calling new to make a pointer to a slice (since it is already a reference type)... but I see this happens all over in this repo, so let's leave it... and maybe some day I can throw together a PR to replace it and see what the other authors think about the change.

Agree that this would be best to tackle in a separate PR since it happens everywhere.

I feel similarly about the whole pattern of returning err instead of nil in situations where err is known to be nil; I will make a PR for that sometime.

OK, I can address this change in a separate PR.
For the record, it will become:

var pendingInvitations []*Invitation resp, err := s.client.Do(req, &pendingInvitations) if err != nil { return nil, resp, err } return pendingInvitations, resp, nil

gmlewis · 2017-01-31T06:06:22Z

github/orgs_teams.go

+	ID    *int    `json:"id,omitempty"`
+	Login *string `json:"login,omitempty"`
+	Email *string `json:"email,omitempty"`
+	// Role can be one of the values - direct_member, admin, billing_manager, hiring_manager, or reinstate.


nit - would you mind putting the acceptable values in quotes to follow the style of the other documentation in the repo?

gmlewis · 2017-01-31T06:07:11Z

github/orgs_teams_test.go

 		testFormValues(t, r, values{"page": "1"})
 		testHeader(t, r, "Accept", mediaTypeOrgMembershipPreview)
-		fmt.Fprint(w, `[{"id":1}]`)
+		fmt.Fprint(w, `[


Can we please reduce this test to just fields of interest?

@gmlewis, @shurcooL I agree I made the test case big with the full test data. I have used all values that are returned by this API call, i felt test coverage will be better that way. I was not sure which field to omit, as JSON will return all of them.
Is there a guideline to choose some of these fields from from the response?

I personally don't mind having all the fields here, since they come directly from GitHub API examples.

If we reduce it to just IDs, keep the new inviter field with an ID too.

gmlewis · 2017-01-31T06:07:30Z

github/orgs_members_test.go

+		testMethod(t, r, "GET")
+		testFormValues(t, r, values{"page": "1"})
+		testHeader(t, r, "Accept", mediaTypeOrgMembershipPreview)
+		fmt.Fprint(w, `[


Can we please reduce this test to just fields of interest?

@gmlewis, @shurcooL, As I mentioned above, I felt all fields need to be tested for assignment to the struct and compare values. Will it be ok only to test id field as before?

@shurcooL @gmlewis thank you

Thank you, @varadarajana!

gmlewis · 2017-02-01T17:16:27Z

LGTM.
Merging.

gmlewis · 2017-02-01T17:27:13Z

Integrated in 0e7db46

Fixes google#514. Closes google#527. Change-Id: Id42e4304aae2388af67dca345bf12aa042b773f1

varadarajana added 3 commits January 21, 2017 11:51

google#514: added inviter to Invitation for orgs and teams invite

74b3db5

google#514: go fmt

4a4a270

google#514: removed prints

3f2f969

google#514: changed time data types and included them in test

1d7107a

google#514 Added Org List Pending Invitations

f5b2eeb

google#514 removed typos in error handling

112d718

dmitshur requested changes Jan 26, 2017

View reviewed changes

dmitshur mentioned this pull request Jan 26, 2017

Support update to organization and team invitations APIs #514

Closed

google#514: Modified to pointer time.Time in Invitation

2a95ca6

dmitshur requested changes Jan 29, 2017

View reviewed changes

varadarajana added 2 commits January 29, 2017 12:57

google#514: Set up Naming conventions for multi words, pointer to bool

6305685

google#514: multi word variable format

1840a00

dmitshur requested changes Jan 29, 2017

View reviewed changes

varadarajana added 2 commits January 30, 2017 20:42

google#514 : used User instead of new struct

5c4cab8

google#514 : removed Inviter struct

e732a04

dmitshur changed the title ~~#514: added inviter to Invitation for teams invite~~ Add ListPendingOrgInvitations method and Invitation.Inviter field. Jan 30, 2017

dmitshur approved these changes Jan 30, 2017

View reviewed changes

dmitshur requested a review from gmlewis January 30, 2017 19:14

dmitshur reviewed Jan 30, 2017

View reviewed changes

gmlewis requested changes Jan 31, 2017

View reviewed changes

varadarajana added 2 commits January 31, 2017 23:16

Merge remote-tracking branch 'upstream/master'

7e8a9ee

google#514: Added quotes to list values in comment

1bd4328

gmlewis approved these changes Feb 1, 2017

View reviewed changes

gmlewis closed this in 0e7db46 Feb 1, 2017

bubg-dev pushed a commit to bubg-dev/go-github that referenced this pull request Jun 16, 2017

Add inviter to Invitation for orgs and teams invite

7c30bb8

Fixes google#514. Closes google#527. Change-Id: Id42e4304aae2388af67dca345bf12aa042b773f1

dmitshur mentioned this pull request Sep 27, 2017

OrganizationsService.ListPendingOrgInvitations does not work #730

Closed

gmlewis mentioned this pull request Feb 22, 2020

Switch Workflow to use pointers #1437

Merged

	// The originating VCS type. Can be one of 'subversion', 'git',
	// 'mercurial', or 'tfvc'. Without this parameter, the import job will

Conversation

varadarajana commented Jan 21, 2017 • edited by dmitshur Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

varadarajana commented Jan 21, 2017

Uh oh!

varadarajana commented Jan 21, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

varadarajana commented Jan 21, 2017

Uh oh!

dmitshur left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmitshur Jan 26, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmitshur left a comment

Choose a reason for hiding this comment

Uh oh!

dmitshur Jan 29, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmitshur left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmitshur Jan 31, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmitshur Jan 31, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

varadarajana commented Jan 21, 2017 •

edited by dmitshur

Loading

varadarajana commented Jan 21, 2017 •

edited

Loading

dmitshur Jan 26, 2017 •

edited

Loading

dmitshur Jan 29, 2017 •

edited

Loading

dmitshur Jan 31, 2017 •

edited

Loading

dmitshur Jan 31, 2017 •

edited

Loading

gmlewis Feb 1, 2017 •

edited by dmitshur

Loading