feat!: Add support for project items CRUD and project fields read operations #3793

stephenotalora · 2025-10-27T21:37:08Z

BREAKING CHANGES:

ProjectV2Field.Options changed from []any to []*ProjectV2FieldOption.
Optional fields in various ProjectV2 structs are now passed as pointers
Aligns ProjectsService functions with Consistent naming for enterprise & organization scoped functions #3761

Closes: #3733.

Based on: #3733

Covers all endpoints for project items : https://docs.github.com/en/rest/projects/items?apiVersion=2022-11-28
Adds support to GET fields on project items, specifically the following REST APIs:

Co-authored-by: Glenn Lewis <6598971+gmlewis@users.noreply.github.com>

…into add-project-items

…d-project-items

google-cla · 2025-10-27T21:37:14Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

stephenotalora · 2025-10-28T22:01:57Z

@stephenotalora - I'm not sure I understand this comment:

It reconciles merge conflicts between upstream/master and the add-project-items branch by synchronizing the branch with the latest master@v76

Also, please change the title of this PR.

Thanks @gmlewis, updated the PR title and PR description, hoping that's a little more clear, let me know if you have any questions.

gmlewis · 2025-10-28T22:05:58Z

Thanks @gmlewis, updated the PR title and PR description, hoping that's a little more clear, let me know if you have any questions.

So the state of the external-to-this-repo branch called "JoannaaKL:stephenotalora/add-project-items" is irrelevant to this PR and all that information in the description and in the PR title should be removed.

We try to make the PR title helpful to understand what this PR is all about.

How about this:

"feat!: Add methods to edit ProjectsV2 fields"

The "feat!:" part is needed because this PR breaks the API from previous versions.

gmlewis

Your PR title now says "GET" but this PR also includes "POST", "PATCH", and "DELETE" methods, so please make the PR title reflect this.

Before I proceed with this PR review, it looks like this PR has some regressions that were already addressed in #3718.

gmlewis · 2025-10-28T22:46:51Z

github/projects.go

 	UpdatedAt        *Timestamp `json:"updated_at,omitempty"`
 	DeletedAt        *Timestamp `json:"deleted_at,omitempty"`
-	Number           *int       `json:"number,omitempty"`
+	Number           *int64     `json:"number,omitempty"`


There was a discussion about this field being of type int because we felt that a project number would not overflow a 32-bit integer.

Why are you changing this here?

Why are you changing this here?

Thanks @gmlewis, I appreciate you resurfacing the previous discussion; I had missed that context earlier. A couple of points that led to this change:

I took over the base PR, at first glance it appeared there was an intentional effort to transition the projectNumber field to an int64.

To validate the assumption:

I checked our internal database schema and found the field defined as an UNSIGNED BIGINT

Additionally, the OpenAPI specification lists this field as an int64

Both of which reinforced the idea that a wider numeric type might be appropriate in Go.

On second thought, though, an UNSIGNED BIGINT doesn’t directly map to a Go int64, since their ranges differ, while a uint64 would technically align more closely, as you described here that would likely add unnecessary complexity given the low risk of overflow for project numbers.

With that in mind, retaining the int type seems appropriate given the prior context. I can update the PR accordingly 👍🏼

updated: fixed in 25561d3

gmlewis · 2025-10-28T22:48:02Z

github/projects.go

-	Color string `json:"color,omitempty"`
-	// An optional description for this option.
-	Description string `json:"description,omitempty"`
+	ID          *int64 `json:"id,omitempty"`          // The unique identifier for this option.


Why is this being changed from a string?
Actually, it should probably be a *string here if it truly is an optional field.

indeed a string as per our API docs - updated in 27dd1c4

gmlewis · 2025-10-28T22:48:56Z

github/projects.go

+	Name        string `json:"name,omitempty"`        // The display name of the option.
+	Color       string `json:"color,omitempty"`       // The color associated with this option (e.g., "blue", "red").
+	Description string `json:"description,omitempty"` // An optional description for this option.


Optional fields should be pointers to strings in general. I'm not sure why these were left as values in #3718.

fixed in 27dd1c4

gmlewis · 2025-10-28T22:53:59Z

github/projects.go

 //
 //meta:operation GET /orgs/{org}/projectsV2/{project_number}
-func (s *ProjectsService) GetProjectForOrg(ctx context.Context, org string, projectNumber int) (*ProjectV2, *Response, error) {
+func (s *ProjectsService) GetProjectForOrg(ctx context.Context, org string, projectNumber int64) (*ProjectV2, *Response, error) {


Here and below, projectNumber should remain as int unless you have a good reason to change them in this PR.

based on this comment - fixed in 25561d3

stephenotalora · 2025-10-29T18:17:54Z

Your PR title now says "GET" but this PR also includes "POST", "PATCH", and "DELETE" methods, so please make the PR title reflect this.

Yes, thank you 🙇🏼 I went through a rather large conflict earlier, and the title reflected the later additions, that’s my oversight. I’ll update accordingly.

update: I've taken the PR back to a draft while I work on edits.
update-2: @gmlewis PR is ready for another pass, thanks for taking the time to review is much appreciated 🙇🏼

gmlewis

Thank you, @stephenotalora.

gmlewis · 2025-10-29T21:54:45Z

github/projects.go

+// GitHub API docs: https://docs.github.com/rest/projects/fields#list-project-fields-for-user
+//
+//meta:operation GET /users/{username}/projectsV2/{project_number}/fields
+func (s *ProjectsService) ListProjectFieldsForUser(ctx context.Context, user string, projectNumber int, opts *ListProjectsOptions) ([]*ProjectV2Field, *Response, error) {


I seem to recall a conversation we had earlier about changing "*ForUser" to (for example) "ListUserProjectFields" but looking through this go-github repo, I see we have both styles and I can't seem to find the conversation, so I'll leave this now and maybe our other reviewers will have an opinion.

Happy to make this change if there’s a strong preference either way. It would be a breaking change on our end, but easy enough to address. I did a quick search across the repo, and it looks like *ForUser and *ForOrg are used fairly extensively, in about 4 and 12 files, respectively.

Suggested change

func (s *ProjectsService) ListProjectFieldsForUser(ctx context.Context, user string, projectNumber int, opts *ListProjectsOptions) ([]*ProjectV2Field, *Response, error) {

func (s *ProjectsService) ListUserProjectFields(ctx context.Context, user string, projectNumber int, opts *ListProjectsOptions) ([]*ProjectV2Field, *Response, error) {

See #3761

github/projects.go

…nsistency

gmlewis

Thank you, @stephenotalora!
LGTM.
Awaiting second LGTM+Approval from any other contributor to this repo before merging.

cc: @stevehipwell - @alexandear - @zyfy29

alexandear · 2025-10-30T17:09:43Z

github/projects.go

+// GitHub API docs: https://docs.github.com/rest/projects/fields#get-project-field-for-organization
+//
+//meta:operation GET /orgs/{org}/projectsV2/{project_number}/fields/{field_id}
+func (s *ProjectsService) GetProjectFieldForOrg(ctx context.Context, org string, projectNumber int, fieldID int64) (*ProjectV2Field, *Response, error) {


Suggested change

func (s *ProjectsService) GetProjectFieldForOrg(ctx context.Context, org string, projectNumber int, fieldID int64) (*ProjectV2Field, *Response, error) {

func (s *ProjectsService) GetOrganizationProjectField(ctx context.Context, org string, projectNumber int, fieldID int64) (*ProjectV2Field, *Response, error) {

See #3761

Thanks for feedback @alexandear, I'll start working on these changes shortly 👍🏼

update: refactored as part of c2f8bfa

alexandear · 2025-10-30T17:10:00Z

github/projects.go

+// GitHub API docs: https://docs.github.com/rest/projects/fields#get-project-field-for-user
+//
+//meta:operation GET /users/{username}/projectsV2/{project_number}/fields/{field_id}
+func (s *ProjectsService) GetProjectFieldForUser(ctx context.Context, user string, projectNumber int, fieldID int64) (*ProjectV2Field, *Response, error) {


Suggested change

func (s *ProjectsService) GetProjectFieldForUser(ctx context.Context, user string, projectNumber int, fieldID int64) (*ProjectV2Field, *Response, error) {

func (s *ProjectsService) GetUserProjectField(ctx context.Context, user string, projectNumber int, fieldID int64) (*ProjectV2Field, *Response, error) {

See #3761

refactored as part of c2f8bfa

alexandear · 2025-10-30T17:10:27Z

github/projects.go

+// GitHub API docs: https://docs.github.com/rest/projects/items#add-item-to-organization-owned-project
+//
+//meta:operation POST /orgs/{org}/projectsV2/{project_number}/items
+func (s *ProjectsService) AddProjectItemForOrg(ctx context.Context, org string, projectNumber int, opts *AddProjectItemOptions) (*ProjectV2Item, *Response, error) {


Suggested change

func (s *ProjectsService) AddProjectItemForOrg(ctx context.Context, org string, projectNumber int, opts *AddProjectItemOptions) (*ProjectV2Item, *Response, error) {

func (s *ProjectsService) AddOrganizationProjectItem(ctx context.Context, org string, projectNumber int, opts *AddProjectItemOptions) (*ProjectV2Item, *Response, error) {

See #3761

refactored as part of 7f8c2f9

…ed naming convention introduced in google#3761 for consistency across the client API.

…ing convention defined in google#3761

…d naming convention defined in google#3761

stephenotalora · 2025-10-30T19:42:41Z

Thank you @gmlewis and @alexandear for taking the time to review this PR; I really appreciate your feedback and attention to detail 🙏🏼

I’ve incorporated the recent suggestions, particularly aligning the function naming conventions for ProjectsService with #3761 in the following commits:

Project-specific methods: 00873b1
Project field methods: c2f8bfa
Project item methods: 7f8c2f9

I also wanted to ask if there's a general expectation regarding the merge and release timeline for this PR. I understand schedules can vary, but having an approximate idea would help with planning once the new APIs become available.

No rush; I just wanted to check in and thank you both again for your time and for maintaining such a valuable library!

gmlewis · 2025-10-30T19:45:13Z

I also wanted to ask if there's a general expectation regarding the merge and release timeline for this PR. I understand schedules can vary, but having an approximate idea would help with planning once the new APIs become
available.

I can cut a release once this gets merged, no problem.

No rush; I just wanted to check in and thank you both again for your time and for maintaining such a valuable library!

Thank you for your patience during the open source review process, and for your contributions!
They are greatly appreciated!

JoannaaKL and others added 29 commits September 17, 2025 14:31

Add support for projects V2

775f0f6

Add test

74712bd

Address feedback

3a8cf0c

Merge branch 'master' into add-projects

b754eeb

Remove header and rename functions

e93ed36

Update comments

99852cf

Copyright update

7664215

Merge branch 'master' into add-projects

89016d9

Update comments

2b94765

Generate docs

a4b0a56

Add list projects option

696102b

Generate openapi docs

469e03a

Results of generate

2dbe5b4

Merge branch 'master' into add-projects

478ef5a

Merge branch 'master' into add-projects

c34802d

Update github/projects.go

053a9e1

Co-authored-by: Glenn Lewis <6598971+gmlewis@users.noreply.github.com>

Rename url in test

680a0d1

Generate again

d8696b4

Merge branch 'master' into add-projects

93dd34f

Shorten functions for orgs

060aaae

Implemented all endpoints for project items

98c28fa

Remove comments

a4b1014

Merge branch 'master' into add-project-items

57766b6

Merge branch 'master' into add-project-items

e59c224

Add tests

4e935dd

Merge remote-tracking branch 'refs/remotes/origin/add-project-items' …

d18c303

…into add-project-items

More tests

0c5356d

Merge remote-tracking branch 'upstream/master' into stephenotalora/ad…

b2388d1

…d-project-items

fixes all conflicts between upstream/master and add-project-items branch

551885f

stephenotalora changed the title ~~Updates add-project-items branch and adds support for field retrieval~~ Updates add-project-items branch with master and implements field retrieval support Oct 28, 2025

stephenotalora changed the title ~~Updates add-project-items branch with master and implements field retrieval support~~ Updates add-project-items branch with master and adds field retrieval support Oct 28, 2025

gmlewis added NeedsReview PR is awaiting a review before merging. Breaking API Change PR will require a bump to the major version num in next release. Look here to see the change(s). labels Oct 28, 2025

stephenotalora changed the title ~~Updates add-project-items branch with master and adds field retrieval support~~ Feat!: Add methods to GET ProjectsV2 fields Oct 28, 2025

gmlewis changed the title ~~Feat!: Add methods to GET ProjectsV2 fields~~ feat!: Add methods to GET ProjectsV2 fields Oct 28, 2025

gmlewis requested changes Oct 28, 2025

View reviewed changes

stephenotalora changed the title ~~feat!: Add methods to GET ProjectsV2 fields~~ feat!: Additional support for project items and fields CRUD operations Oct 29, 2025

stephenotalora marked this pull request as draft October 29, 2025 18:43

stephenotalora changed the title ~~feat!: Additional support for project items and fields CRUD operations~~ feat!: Add support for project items CRUD and project fields read operations Oct 29, 2025

stephenotalora added 2 commits October 29, 2025 13:12

reverts projectNumber from int64 to int

25561d3

fixes ProjectV2FieldOption.ID type from int64 to string

27dd1c4

stephenotalora marked this pull request as ready for review October 29, 2025 21:18

stephenotalora requested a review from gmlewis October 29, 2025 21:21

gmlewis requested changes Oct 29, 2025

View reviewed changes

stephenotalora added 3 commits October 29, 2025 16:30

ensures projectNumber is an int across the board

eac21dc

makes all optional fields in existing structs reference types

31e34f0

additional updates following struct changes to reference types for co…

032e591

…nsistency

gmlewis approved these changes Oct 29, 2025

View reviewed changes

alexandear reviewed Oct 30, 2025

View reviewed changes

stephenotalora added 3 commits October 30, 2025 13:10

Refactors project field specific method names to match the standardiz…

c2f8bfa

…ed naming convention introduced in google#3761 for consistency across the client API.

Refactors project specific method names to adhere to standardized nam…

00873b1

…ing convention defined in google#3761

Refctors project items specific method names to adhere to standardize…

7f8c2f9

…d naming convention defined in google#3761

stephenotalora requested a review from alexandear October 30, 2025 21:00

additional cleanup due to refactor

8437626

	func (s ProjectsService) ListProjectFieldsForUser(ctx context.Context, user string, projectNumber int, opts ListProjectsOptions) ([]ProjectV2Field, Response, error) {
	func (s ProjectsService) ListUserProjectFields(ctx context.Context, user string, projectNumber int, opts ListProjectsOptions) ([]ProjectV2Field, Response, error) {

	func (s ProjectsService) GetProjectFieldForOrg(ctx context.Context, org string, projectNumber int, fieldID int64) (ProjectV2Field, *Response, error) {
	func (s ProjectsService) GetOrganizationProjectField(ctx context.Context, org string, projectNumber int, fieldID int64) (ProjectV2Field, *Response, error) {

	func (s ProjectsService) GetProjectFieldForUser(ctx context.Context, user string, projectNumber int, fieldID int64) (ProjectV2Field, *Response, error) {
	func (s ProjectsService) GetUserProjectField(ctx context.Context, user string, projectNumber int, fieldID int64) (ProjectV2Field, *Response, error) {

	func (s ProjectsService) AddProjectItemForOrg(ctx context.Context, org string, projectNumber int, opts AddProjectItemOptions) (ProjectV2Item, Response, error) {
	func (s ProjectsService) AddOrganizationProjectItem(ctx context.Context, org string, projectNumber int, opts AddProjectItemOptions) (ProjectV2Item, Response, error) {

feat!: Add support for project items CRUD and project fields read operations #3793

Are you sure you want to change the base?

feat!: Add support for project items CRUD and project fields read operations #3793

Conversation

stephenotalora commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

google-cla bot commented Oct 27, 2025

Uh oh!

stephenotalora commented Oct 28, 2025

Uh oh!

gmlewis commented Oct 28, 2025

Uh oh!

gmlewis left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephenotalora Oct 29, 2025 • 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!

stephenotalora Oct 29, 2025 • 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!

stephenotalora commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gmlewis 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gmlewis left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephenotalora Oct 30, 2025 • 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!

stephenotalora commented Oct 30, 2025

Uh oh!

gmlewis commented Oct 30, 2025

Uh oh!

Reviewers

Assignees

stephenotalora commented Oct 27, 2025 •

edited

Loading

stephenotalora Oct 29, 2025 •

edited

Loading

stephenotalora Oct 29, 2025 •

edited

Loading

stephenotalora commented Oct 29, 2025 •

edited

Loading

stephenotalora Oct 30, 2025 •

edited

Loading