Consistent Go naming for JSON fields

[gmlewis]

As discussed in #520 (comment) and #602 (comment) the naming of fields such as Total (as opposed to TotalCount) where the JSON name is total_count seems inconsistent and it would be nice to consolidate.

However, this is a breaking API change.

This issue has been opened to discuss the situation and see if it is worth breaking the API to have more consistency.

[dmitshur]

We can also consider adding a new field TotalCount that also gets decoded from `json:"total_count"`, and mark the old Total as deprecated. That way it's not a breaking API change, but it introduces a deprecated field.

[gmlewis]

Good point. I like it. Maybe a general sweep might be in order.
It would be a good project for a new contributor too.

[aleksclark]

@gmlewis I'm down for doing it either way, but #588 is already unavoidably (afaics, unless we want to return interface{} which I would personally frown on) a breaking change for an actual bug. Is there a deprecation/semver policy somewhere I've missed that can be a guide for making these sorts of calls? Perhaps the deprecate-and-replace method should be used for #588 as well?

[gmlewis]

The semver discussion is going on in #376.
Otherwise, we bump the libraryVersion number in github.go on breaking API changes.
Part of the resolution of #376 will be to document the policy.

[aleksclark]

ok, I'll proceed as described with the deprecated fields and increment the version number.

[aleksclark]

https://github.com/google/go-github/blob/master/github/activity_events.go#L19

RawPayload is used here despite the fact that the field is called payload. The struct then implements a Payload() method which is already deprecated, as well as a ParsePayload() method which is the new hotness. Seems reasonable to me to rename RawPayload to Payload and remove the deprecated method. On the other hand, this deprecation is only 23 days old. Thoughts?

[dmitshur]

IMO, it's probably for the best to leave RawPayload alone for now. It has a lot of machinery around it to parse it and convert it to something higher level, such that calling the field "raw" should not be confusing.

The only field I think is worth dealing with for now is TotalCount. @gmlewis, are there others you wanted to tackle?

[aleksclark]

Hmm, ok. I interpreted 'full sweep' to mean all json fields should be inspected for naming consistency. For instance, there is a lot of swapping of 'Repo' and 'repository', and at least one place where the field is called Repository but the json field is 'repo'.

…

On Fri, Mar 31, 2017 at 4:43 PM, Dmitri Shuralyov ***@***.***> wrote: IMO, it's probably for the best to leave RawPayload alone for now. It has a lot of machinery around it to parse it and convert it to something higher level, that calling that field "raw" should not be confusing. The only field I think is worth dealing with for now is TotalCount. @gmlewis <https://github.com/gmlewis>, are there others you wanted to tackle? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#605 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAlDnB4lqlyU_zQ389zxRW5mp5RTuuhAks5rrXN_gaJpZM4Mtrr-> .

-- Aleks Clark cell: 775-391-6114

[dmitshur]

Maybe a general sweep might be in order.

Ah, @gmlewis said that in a comment, not the original issue. I missed that.

Sure. A general sweep is okay. I think RawPayload field is not a good candidate (for reasons I stated above), but perhaps there are others that are. Let us know if you find something else.

[dmitshur]

One of my worries about a full sweep is that it might be hard to justify renaming fields that are well named but happen not to match exactly. It introduces a new deprecated field, and I'm not entirely sure it's always an improvement. But let's consider it on a case-by-case basis.

[gmlewis]

The only field I think is worth dealing with for now is TotalCount. @gmlewis, are there others you wanted to tackle?

I think TotalCount was the most obvious. Maybe whoever tackles this one could come up with a list of inconsistencies for review?

[aleksclark]

@gmlewis sounds good to me. Can you assign to me please?

…

On Fri, Mar 31, 2017 at 5:01 PM, Glenn Lewis ***@***.***> wrote: I think TotalCount was the most obvious. Maybe whoever tackles this one could come up with a list of inconsistencies for review? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#605 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAlDnPWFyebSVqgWU3O7qYtoER7PRbKDks5rrXfUgaJpZM4Mtrr-> .

-- Aleks Clark cell: 775-391-6114