fix!: Fix field selection and bugs in ProjectsV2 GET endpoints (#3809)

BREAKING CHANGE: `UpdateProjectItemOptions.Field` is now `[]*ProjectV2FieldUpdate`.

Author: stephenotalora

github/event_types.go

@@ -1148,20 +1148,42 @@ type FieldValue struct {
 	To            json.RawMessage `json:"to,omitempty"`
 }
 
+// ProjectV2ItemFieldValue represents a field value of a project item.
+type ProjectV2ItemFieldValue struct {
+	ID       *int64 `json:"id,omitempty"`
+	Name     string `json:"name,omitempty"`
+	DataType string `json:"data_type,omitempty"`
+	// Value set for the field. The type depends on the field type:
+	//   - text: string
+	//   - number: float64
+	//   - date: string (ISO 8601 date format, e.g. "2023-06-23") or null
+	//   - single_select: object with "id", "name", "color", "description" fields or null
+	//   - iteration: object with "id", "title", "start_date", "duration" fields or null
+	//   - title: object with "text" field (read-only, reflects the item's title) or null
+	//   - assignees: array of user objects with "login", "id", etc. or null
+	//   - labels: array of label objects with "id", "name", "color", etc. or null
+	//   - linked_pull_requests: array of pull request objects or null
+	//   - milestone: milestone object with "id", "title", "description", etc. or null
+	//   - repository: repository object with "id", "name", "full_name", etc. or null
+	//   - reviewers: array of user objects or null
+	//   - status: object with "id", "name", "color", "description" fields (same structure as single_select) or null
+	Value any `json:"value,omitempty"`
+}
+
 // ProjectV2Item represents an item belonging to a project.
 type ProjectV2Item struct {
-	ID            *int64            `json:"id,omitempty"`
-	NodeID        *string           `json:"node_id,omitempty"`
-	ProjectNodeID *string           `json:"project_node_id,omitempty"`
-	ContentNodeID *string           `json:"content_node_id,omitempty"`
-	ProjectURL    *string           `json:"project_url,omitempty"`
-	ContentType   *string           `json:"content_type,omitempty"`
-	Creator       *User             `json:"creator,omitempty"`
-	CreatedAt     *Timestamp        `json:"created_at,omitempty"`
-	UpdatedAt     *Timestamp        `json:"updated_at,omitempty"`
-	ArchivedAt    *Timestamp        `json:"archived_at,omitempty"`
-	ItemURL       *string           `json:"item_url,omitempty"`
-	Fields        []*ProjectV2Field `json:"fields,omitempty"`
+	ID            *int64                     `json:"id,omitempty"`
+	NodeID        *string                    `json:"node_id,omitempty"`
+	ProjectNodeID *string                    `json:"project_node_id,omitempty"`
+	ContentNodeID *string                    `json:"content_node_id,omitempty"`
+	ProjectURL    *string                    `json:"project_url,omitempty"`
+	ContentType   *string                    `json:"content_type,omitempty"`
+	Creator       *User                      `json:"creator,omitempty"`
+	CreatedAt     *Timestamp                 `json:"created_at,omitempty"`
+	UpdatedAt     *Timestamp                 `json:"updated_at,omitempty"`
+	ArchivedAt    *Timestamp                 `json:"archived_at,omitempty"`
+	ItemURL       *string                    `json:"item_url,omitempty"`
+	Fields        []*ProjectV2ItemFieldValue `json:"fields,omitempty"`
 }
 
 // PublicEvent is triggered when a private repository is open sourced.

github/github-accessors.go

@@ -74,26 +74,35 @@ type ListProjectsOptions struct {
 	Query *string `url:"q,omitempty"`
 }
 
+// ProjectV2TextContent represents text content in a project field option or iteration.
+// It includes both HTML and raw text representations.
+//
+// GitHub API docs: https://docs.github.com/rest/projects/fields
+type ProjectV2TextContent struct {
+	HTML *string `json:"html,omitempty"`
+	Raw  *string `json:"raw,omitempty"`
+}
+
 // ProjectV2FieldOption represents an option for a project field of type single_select or multi_select.
 // It defines the available choices that can be selected for dropdown-style fields.
 //
 // GitHub API docs: https://docs.github.com/rest/projects/fields
 type ProjectV2FieldOption struct {
-	ID          *string `json:"id,omitempty"`          // The unique identifier for this option.
-	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.
+	ID          *string               `json:"id,omitempty"`          // The unique identifier for this option.
+	Color       *string               `json:"color,omitempty"`       // The color associated with this option (e.g., "blue", "red").
+	Description *ProjectV2TextContent `json:"description,omitempty"` // An optional description for this option.
+	Name        *ProjectV2TextContent `json:"name,omitempty"`        // The display name of the option.
 }
 
 // ProjectV2FieldIteration represents an iteration within a project field of type iteration.
 // It defines a specific time-bound period that can be associated with project items.
 //
 // GitHub API docs: https://docs.github.com/rest/projects/fields
 type ProjectV2FieldIteration struct {
-	ID        *string `json:"id,omitempty"`         // The unique identifier for the iteration.
-	Title     *string `json:"title,omitempty"`      // The title of the iteration.
-	StartDate *string `json:"start_date,omitempty"` // The start date of the iteration in ISO 8601 format.
-	Duration  *int    `json:"duration,omitempty"`   // The duration of the iteration in seconds.
+	ID        *string               `json:"id,omitempty"`         // The unique identifier for the iteration.
+	Title     *ProjectV2TextContent `json:"title,omitempty"`      // The title of the iteration.
+	StartDate *string               `json:"start_date,omitempty"` // The start date of the iteration in ISO 8601 format.
+	Duration  *int                  `json:"duration,omitempty"`   // The duration of the iteration in seconds.
 }
 
 // ProjectV2FieldConfiguration represents the configuration for a project field of type iteration.
@@ -325,14 +334,31 @@ type AddProjectItemOptions struct {
 	ID   int64  `json:"id,omitempty"`
 }
 
+// UpdateProjectV2Field represents a field update for a project item.
+//
+// GitHub API docs: https://docs.github.com/rest/projects/items#update-project-item-for-organization
+type UpdateProjectV2Field struct {
+	// ID is the field ID to update.
+	ID int64 `json:"id"`
+	// Value is the new value to set for the field. The type depends on the field type.
+	// For text fields: string
+	// For number fields: float64 or int
+	// For single_select fields: string (option ID)
+	// For date fields: string (ISO 8601 date)
+	// For iteration fields: string (iteration ID)
+	// Note: Some field types (title, assignees, labels, etc.) are read-only or managed through other API endpoints.
+	Value any `json:"value"`
+}
+
 // UpdateProjectItemOptions represents fields that can be modified for a project item.
-// Currently the REST API allows archiving/unarchiving an item (archived boolean).
-// This struct can be expanded in the future as the API grows.
+// The GitHub API expects either archived status updates or field value updates.
 type UpdateProjectItemOptions struct {
 	// Archived indicates whether the item should be archived (true) or unarchived (false).
+	// This is used for archive/unarchive operations.
 	Archived *bool `json:"archived,omitempty"`
-	// Fields allows updating field values for the item. Each entry supplies a field ID and a value.
-	Fields []*ProjectV2Field `json:"fields,omitempty"`
+	// Fields contains field updates to apply to the project item.
+	// Each entry specifies a field ID and its new value.
+	Fields []*UpdateProjectV2Field `json:"fields,omitempty"`
 }
 
 // ListOrganizationProjectItems lists items for an organization owned project.
@@ -387,7 +413,11 @@ func (s *ProjectsService) AddOrganizationProjectItem(ctx context.Context, org st
 //meta:operation GET /orgs/{org}/projectsV2/{project_number}/items/{item_id}
 func (s *ProjectsService) GetOrganizationProjectItem(ctx context.Context, org string, projectNumber int, itemID int64, opts *GetProjectItemOptions) (*ProjectV2Item, *Response, error) {
 	u := fmt.Sprintf("orgs/%v/projectsV2/%v/items/%v", org, projectNumber, itemID)
-	req, err := s.client.NewRequest("GET", u, opts)
+	u, err := addOptions(u, opts)
+	if err != nil {
+		return nil, nil, err
+	}
+	req, err := s.client.NewRequest("GET", u, nil)
 	if err != nil {
 		return nil, nil, err
 	}
@@ -481,7 +511,11 @@ func (s *ProjectsService) AddUserProjectItem(ctx context.Context, username strin
 //meta:operation GET /users/{username}/projectsV2/{project_number}/items/{item_id}
 func (s *ProjectsService) GetUserProjectItem(ctx context.Context, username string, projectNumber int, itemID int64, opts *GetProjectItemOptions) (*ProjectV2Item, *Response, error) {
 	u := fmt.Sprintf("users/%v/projectsV2/%v/items/%v", username, projectNumber, itemID)
-	req, err := s.client.NewRequest("GET", u, opts)
+	u, err := addOptions(u, opts)
+	if err != nil {
+		return nil, nil, err
+	}
+	req, err := s.client.NewRequest("GET", u, nil)
 	if err != nil {
 		return nil, nil, err
 	}