<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/engineering/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Label this issue](https://contributors.gitlab.com/manage-issue?action=label&projectId=65271576&issueIid=2301) </details> <!--IssueSummary end--> ## Summary !3063 fixes places where this library and the GitLab API disagree. Where the right fix would remove an exported name, change a method's signature or change a field's type, it does the half that keeps v3 source compatible and leaves the rest for 4.0. The one exception is the pipeline cancellation role: after the review, !3063 gives the two `CIRestrictPipelineCancellationRole` fields a type of their own now. If !3063 drops that change, it comes back to this list. One change of behavior, what a nil options pointer sends, is made opt-in instead, in !3065, which the review split out of !3063, and its default follows in 4.0. This issue tracks the rest, as the [review of !3063](https://gitlab.com/gitlab-org/api/client-go/-/merge_requests/3063#note_3920279951) asked. ## Why deferred Each change below removes an exported name, changes a method's signature, changes a field's type or changes what a request sends by default, so it breaks existing callers and has to wait for a major version. ## What 4.0 does ### 1. Methods that return a type their endpoint does not send Each has a `V2` sibling with the right return type, and the original is deprecated in its favour. In 4.0 the original name takes the `V2` signature and the `V2` method is removed. | Deprecated method | Returns today | `V2` returns | |---|---|---| | `DeploymentsService.ApproveOrRejectProjectDeployment` | nothing (the approval is discarded) | `*DeploymentApproval` | | `GeoSitesService.RepairGeoSite` | `*GeoSite` | `*GeoSiteStatus` | | `MergeRequestsService.CreateMergeRequestPipeline` | `*PipelineInfo` | `*Pipeline` | | `ProjectsService.CreateProjectForkRelation` | `*ProjectForkRelation` | `*Project` | | `ProjectsService.ShareProjectWithGroup` | nothing (the link is discarded) | `*ProjectGroupLink` | | `UsersService.CreateServiceAccountUser` | `*User` | `*ServiceAccount` | `ProjectForkRelation`, which no GitLab entity exposes, is removed with them. `CreateMergeRequestPipelineV2` also takes the route's `async` option. ### 2. Methods that take no options although their routes do In 4.0 the base method takes the options struct. The `WithOptions` sibling stays, deprecated, and is removed in 5.0: - `WorkItemsService.GetWorkItem` and `GetWorkItemWithOptions` (from !3063) - `ProjectMembersService.DeleteProjectMember` and `DeleteProjectMemberWithOptions` (from !3063) - `JobsService.CancelJob`, `DraftNotesService.PublishAllDraftNotes` and `JobsService.GetJobArtifacts`, whose siblings already follow the same pattern and would follow the same schedule All five siblings already carry `Deprecated` notes that tie them to 4.0, which this schedule makes wrong: each should either say 5.0, or come out until 4.0 deprecates the sibling. ### 3. A field typed narrower than what GitLab sends `GeoSiteStatus.Namespaces` is a `[]string` where GitLab sends namespace objects. !3063 keeps the full paths there and puts the objects in `NamespaceDetails`. In 4.0 the field takes the object type and `NamespaceDetails` is removed. `Epic.Labels` needs nothing here: it keeps the names and puts the objects in `LabelDetails`, which is the shape `Issue` and `MergeRequest` already have. ### 4. Fields current GitLab does not send, and option fields no current route declares !3063 deprecates each of these with a note saying why, and what to read instead where GitLab sends the value under another name. In 4.0 they are removed: - `AuditEvent.EventType` - `ContributionEvent.Title`, `ProjectEvent.Title`, `ProjectEvent.Data` - `Epic.UserNotesCount` - `Group.DuoAvailability` - `Integration.GroupMentionEvents`, `Integration.GroupConfidentialMentionEvents` - `Issue.IssueLinkID`, which GitLab sends only on the issue links route, decoded there into `IssueRelation` - `LicenseTemplate.Featured` - `Note.Attachment`, `Note.ExpiresAt`, `Note.FileName`, `Note.Title`, `NoteAuthor.Email`, `NoteResolvedBy.Email` - `PendingInvite.ID` - `PipelineTrigger.DeletedAt` - `Project.BuildCoverageRegex`, `Project.CIOptInJWT`, `Project.OperationsAccessLevel` - `CreateProjectOptions.BuildCoverageRegex`, `CreateProjectOptions.OperationsAccessLevel`, `EditProjectOptions.BuildCoverageRegex`, `EditProjectOptions.OperationsAccessLevel` - `ReleaseLink.External`, which GitLab removed from the release link API in 16.0 - `User.CanCreateOrganization`, `User.ExternUID`, `User.Provider`, `User.Skype` - `CreateUserOptions.Skype`, `ModifyUserOptions.Skype` - `WeightEvent.ResourceID`, `WeightEvent.ResourceType`, `WeightEvent.State` Older releases, all out of maintenance, did send some of these, for example `Project.BuildCoverageRegex` up to 15.2, `Project.CIOptInJWT` from 15.2 to 15.11, `Project.OperationsAccessLevel` and `ReleaseLink.External` up to 15.11, `Note.Attachment` up to 17.10, and `User.Skype` up to 18.1. ### 5. Structs that decode more than one entity `Group`, `Project` and `Issue` each decode a narrow Grape entity and one or more wider ones that inherit it: - `BasicGroupDetails` on the job token groups allowlist, `Entities::Group` on the group listings, and `GroupDetail` on the routes that answer with one group - `BasicProjectDetails` on a project listing with `simple` or without authentication, `ProjectDetails` on a single project read without authentication, and `Project` or an entity inheriting it otherwise - `IssueBasic` where other APIs render an issue (a milestone's issues, the issues a merge request closes, search), and `Issue` on the issues API's own routes `User` decodes six. !3063 puts the new fields on the one struct, with comments saying when GitLab sends each. In 4.0 a route that answers with a narrower entity returns a struct shaped like it. `BasicUser` already has the shape of `UserBasic`, but `BasicProject` has the shape of the smaller `ProjectIdentity` rather than `BasicProjectDetails`, and no struct has the shape of `Entities::Group` or `IssueBasic`, so `Project`, `Group` and `Issue` each still need another struct. ### 6. A nil options pointer sends `null` by default A nil `*Options` held in an `any` is not `nil`, so a POST, PUT or PATCH request given one sends the JSON literal `null` as its body, and a request with any other method has a query already on its URL replaced with an empty one. `JobsService.CancelJob` and `DraftNotesService.PublishAllDraftNotes` do this on their own, through their `WithOptions` siblings. !3065 adds the client option `WithNilOptionsOmitted()`, off by default, which makes such a pointer mean no options. As the [review of !3063](https://gitlab.com/gitlab-org/api/client-go/-/merge_requests/3063#note_3924608467) asked, 4.0 makes that the default, where the option has no effect, and 5.0 removes the option. ## Not part of this `GetMergeRequestChanges` and `ChangeApprovalConfiguration` return `*MergeRequest` for endpoints that answer with `MergeRequestChanges` and `ApprovalState`. GitLab deprecated both endpoints and both methods are already deprecated here. They stay as they are: deprecated routes live a long time in GitLab, and callers may target older instances. ## Next steps - Add this issue to the 4.0 milestone once there is one. - Land each item in the 4.0 release branch, together with the removal of the deprecation notes it retires. Related: !3063, !3065