Add deprecation notice for GlobalID compatibility layer
Be sure to link this MR to the relevant deprecation issue(s).
Adds a deprecation notice for the GraphQL ID
/GlobalID
compatibility layer.
See: #257883 (closed)
- Deprecation Issue: #352832 (closed)
By the 10th: Assign this MR to these team members as Reviewer and for Approval (optional unless noted as required):
- Product Marketing:
@PMM
- Product Designer(s):
@ProductDesigners
- Product Group Manager or Director: @g.hickman
- Engineering Manager: @arturoherrero
- Technical writer: @kpaizee
By 11:59 AM PDT 15th: EM/PM assigns this MR to the TW reviewer for final review and merge: @arturoherrero
By 11:59 PM PDT 17th: TW Reviewer updates Docs by merging this MR to master
: @kpaizee
Please review the guidelines for deprecations, as well as the process for creating a deprecation entry. They are frequently updated, and everyone should make sure they are aware of the current standards (PM, PMM, EM, and TW).
EM/PM release post item checklist
-
Set yourself as the Assignee, meaning you are the DRI. -
If the deprecation is a breaking change, add label breaking change
. -
Follow the process to create a deprecation YAML file. -
Add reviewers by the 10th. -
When ready to be merged and not later than the 15th, add the ~ready
label and @ message the TW for final review and merge.
Reviewers
When the content is ready for review, it must be reviewed by a Technical Writer and Engineering Manager, but can also be reviewed by
Product Marketing, Product Design, and the Product Leaders for this area. Please use the
Reviewers for Merge Requests
feature for all reviews. Reviewers will then approve
the MR and remove themselves from Reviewers when their review is complete.
-
(Recommended) PMM -
(Optional) Product Designer -
(Optional) Group Manager or Director -
Required review and approval: Technical Writer designated to the corresponding DevOps stage/group.
Tech writer review
After being added as a Reviewer to this merge request, the TW performs their review according to the criteria described below.
Review deprecation MRs with a similar process as regular docs MRs. Add suggestions as needed, @ message the PM to inform them the first review is complete, and remove yourself as a reviewer if it's not ready for merge yet.
Expand for Details
-
Title: - Length limit: 7 words (not including articles or prepositions).
- Capitalization: ensure the title is sentence cased.
- Rewrite to exclude the words
deprecation
,deprecate
,removal
, andremove
if necessary.
-
Consistency: - Ensure that all resources (docs, deprecation, etc.) refer to the feature with the same term / feature name.
-
Content: - Make sure the deprecation is accurate based on your understanding. Look for typos or grammar mistakes. Work with PM and PMM to ensure a consistent GitLab style and tone for messaging, based on other features and deprecations.
- Review use of whitespace and bullet lists. Will the deprecation item be easily scannable when published? Consider adding line breaks or breaking content into bullets if you have more than a few sentences.
- Make sure there aren't acronyms readers may not understand per https://about.gitlab.com/handbook/communication/#writing-style-guidelines.
-
Links: - All links must be full URLs, as the deprecation YAML files are used in two different projects. Do not use relative links. The generated doc is an exception to the relative link rule and currently uses absolute links only.
- Make sure all links and anchors are correct. Do not link to the H1 (top) anchor on a docs page.
-
Code. Make sure any included code is wrapped in code blocks. -
Capitalization. Make sure to capitalize feature names. Stay consistent with the Documentation Style Guidance on Capitalization. -
Blank spaces. Remove unnecessary spaces (end of line spaces, double spaces, extra blank lines, and lines with only spaces).
When the PM indicates it is ready for merge and all issues have been addressed, start the merge process.
Technical writer merge process
The deprecations doc's .md
file
must be updated before this MR is merged:
- Check out the MR's branch (in the
gitlab-org/gitlab
project). - From the command line (in the branch), run
bin/rake gitlab:docs:compile_deprecations
. If you want to double check that it worked, you can runbin/rake gitlab:docs:check_deprecations
to verify that the doc is up to date. - Commit the updated file and push the changes.
- Set the MR to merge when the pipeline succeeds (or merge if the pipeline is already complete).
If you have trouble running the Rake task, check the troubleshooting steps.
Merge request reports
Activity
changed milestone to %14.8
added Category:API GraphQL Stretch auto updated backend groupintegrations [DEPRECATED] sectiondev typemaintenance + 1 deleted label
assigned to @alexkalderimis
added deprecation documentation labels
@arturoherrero - could you please take a look at this deprecation notice and give me any feedback you have before I pass it on to a Technical Writing reviewer?
requested review from @arturoherrero
mentioned in issue #257883 (closed)
1 Message 📖 This merge request adds or changes documentation files. A review from the Technical Writing team before you merge is recommended. Reviews can happen after you merge. Documentation review
The following files require a review from a technical writer:
doc/update/deprecations.md
The review does not need to block merging this merge request. See the:
-
Metadata for the
*.md
files that you've changed. The first few lines of each*.md
file identify the stage and group most closely associated with your docs change. - The Technical Writer assigned for that stage and group.
- Documentation workflows for information on when to assign a merge request for review.
If needed, you can retry the
danger-review
job that generated this comment.Generated by
🚫 Dangeradded workflowin dev label
- Resolved by Arturo Herrero
- Resolved by Arturo Herrero
@alexkalderimis Looks good to me, just a small suggestion !80636 (comment 842311805) for your consideration.
Is the GraphQL reference aligned with these changes or do we have to update anything else?
https://docs.gitlab.com/ee/api/graphql/reference/#queryissue
requested review from @digitalmoksha
👋 @arturoherrero
, thanks for approving this merge request.This is the first time the merge request is approved. To ensure full test coverage, a new pipeline has been started.
For more info, please refer to the following links:
removed review request for @arturoherrero
added 1 commit
- a5fc99c3 - Add deprecation notice for GlobalID compatibility layer
- Resolved by Alex Kalderimis
@digitalmoksha - do you think we should provide or link to instructions for how to validate queries using client-side validation? Or should we assume that anyone making use of GraphQL would understand how to do that?
Here is the full list of affected fields, in case anyone thinks we need to put this information anywhere:
Query.snippets(ids: [SnippetID!]) Query.snippets(authorId: UserID) Query.snippets(projectId: ProjectID) Query.milestone(id: MilestoneID!) Query.containerRepository(id: ContainerRepositoryID!) Query.package(id: PackagesPackageID!) Query.user(id: UserID) Query.issue(id: IssueID!) Query.mergeRequest(id: MergeRequestID!) Query.runnerSetup(projectId: ProjectID) Query.runnerSetup(groupId: GroupID) Query.runner(id: CiRunnerID!) Query.timelogs(projectId: ProjectID) Query.timelogs(groupId: GroupID) Query.boardList(id: ListID!) Query.iteration(id: IterationID!) Query.vulnerabilities(scannerId: [VulnerabilitiesScannerID!]) Query.vulnerabilities(clusterId: [ClustersClusterID!]) Query.vulnerabilities(clusterAgentId: [ClustersAgentID!]) Query.vulnerability(id: VulnerabilityID!) Query.devopsAdoptionEnabledNamespaces(displayNamespaceId: NamespaceID) Query.ciMinutesUsage(namespaceId: NamespaceID) Project.sentryDetailedError(id: GitlabErrorTrackingDetailedErrorID!) Project.snippets(ids: [SnippetID!]) Project.boards(id: BoardID) Project.board(id: BoardID!) Project.alertManagementHttpIntegrations(id: AlertManagementHttpIntegrationID) Project.timelogs(projectId: ProjectID) Project.timelogs(groupId: GroupID) Project.vulnerabilities(scannerId: [VulnerabilitiesScannerID!]) Project.vulnerabilities(clusterId: [ClustersClusterID!]) Project.vulnerabilities(clusterAgentId: [ClustersAgentID!]) Project.vulnerabilitySeveritiesCount(scannerId: [VulnerabilitiesScannerID!]) Project.iterations(iterationCadenceIds: [IterationsCadenceID!]) Project.iterationCadences(id: IterationsCadenceID) Project.dastProfile(id: DastProfileID!) Project.dastSiteProfile(id: DastSiteProfileID!) Project.incidentManagementEscalationPolicy(id: IncidentManagementEscalationPolicyID!) Project.incidentManagementTimelineEvents(incidentId: IssueID!) Project.incidentManagementTimelineEvent(incidentId: IssueID!) Project.incidentManagementTimelineEvent(id: IncidentManagementTimelineEventID!) Project.networkPolicies(environmentId: EnvironmentID) Namespace.complianceFrameworks(id: ComplianceManagementFrameworkID) Namespace.complianceFrameworks(id: ComplianceManagementFrameworkID) Group.boards(id: BoardID) Group.board(id: BoardID!) Group.timelogs(projectId: ProjectID) Group.timelogs(groupId: GroupID) Group.epicBoard(id: BoardsEpicBoardID!) Group.iterations(iterationCadenceIds: [IterationsCadenceID!]) Group.iterationCadences(id: IterationsCadenceID) Group.vulnerabilities(scannerId: [VulnerabilitiesScannerID!]) Group.vulnerabilities(clusterId: [ClustersClusterID!]) Group.vulnerabilities(clusterAgentId: [ClustersAgentID!]) Group.vulnerabilitySeveritiesCount(scannerId: [VulnerabilitiesScannerID!]) User.authoredMergeRequests(projectId: ProjectID) User.assignedMergeRequests(projectId: ProjectID) User.reviewRequestedMergeRequests(projectId: ProjectID) User.snippets(ids: [SnippetID!]) User.timelogs(projectId: ProjectID) User.timelogs(groupId: GroupID) MemberInterface.mergeRequestInteraction(id: MergeRequestID!) MemberInterface.mergeRequestInteraction(id: MergeRequestID!) MemberInterface.mergeRequestInteraction(id: MergeRequestID!) Design.versions(earlierOrEqualToId: DesignManagementVersionID) DesignVersion.designsAtVersion(ids: [DesignManagementDesignID!]) DesignVersion.designAtVersion(designId: DesignManagementDesignID) DesignVersion.designAtVersion(id: DesignManagementDesignAtVersionID) Pipeline.job(id: JobID) User.authoredMergeRequests(projectId: ProjectID) User.assignedMergeRequests(projectId: ProjectID) User.reviewRequestedMergeRequests(projectId: ProjectID) User.snippets(ids: [SnippetID!]) User.timelogs(projectId: ProjectID) User.timelogs(groupId: GroupID) User.authoredMergeRequests(projectId: ProjectID) User.assignedMergeRequests(projectId: ProjectID) User.reviewRequestedMergeRequests(projectId: ProjectID) User.snippets(ids: [SnippetID!]) User.timelogs(projectId: ProjectID) User.timelogs(groupId: GroupID) User.authoredMergeRequests(projectId: ProjectID) User.assignedMergeRequests(projectId: ProjectID) User.reviewRequestedMergeRequests(projectId: ProjectID) User.snippets(ids: [SnippetID!]) User.timelogs(projectId: ProjectID) User.timelogs(groupId: GroupID) DesignCollection.designs(atVersion: DesignManagementVersionID) DesignCollection.designs(ids: [DesignManagementDesignID!]) DesignCollection.versions(earlierOrEqualToId: DesignManagementVersionID) DesignCollection.version(id: DesignManagementVersionID) DesignCollection.designAtVersion(id: DesignManagementDesignAtVersionID!) DesignCollection.design(id: DesignManagementDesignID) IncidentManagementOncallSchedule.rotation(id: IncidentManagementOncallRotationID!) Board.lists(id: ListID) EpicBoard.lists(id: BoardsEpicListID) SentryErrorCollection.detailedError(id: GitlabErrorTrackingDetailedErrorID!) SentryErrorCollection.errorStackTrace(id: GitlabErrorTrackingDetailedErrorID!) DesignManagement.version(id: DesignManagementVersionID!) DesignManagement.designAtVersion(id: DesignManagementDesignAtVersionID!) InstanceSecurityDashboard.vulnerabilitySeveritiesCount(scannerId: [VulnerabilitiesScannerID!]) Subscription.issuableAssigneesUpdated(issuableId: IssuableID!) Subscription.issueCrmContactsUpdated(issuableId: IssuableID!) Subscription.issuableTitleUpdated(issuableId: IssuableID!)
this can be generated with the following script in the console:
::Types::GlobalIDType.define_singleton_method(:id_type_names) { @id_types.values.map(&:graphql_name) } gid_types = ::Types::GlobalIDType.id_type_names.to_set fs = GitlabSchema.types.values.flat_map { _1.try(:fields).try(:values) }.compact with_args = fs.select { _1.try(:arguments).present? } def as_str(field, arg_name, arg) "#{field.owner.graphql_name}.#{field.graphql_name}(#{arg_name}: #{arg.type.to_graphql})" end with_args.each do |f| f.arguments.each do |name, arg| puts as_str(f, name, arg) if gid_types.include?(arg.type.unwrap.graphql_name) end end
removed review request for @digitalmoksha
- Resolved by Alex Kalderimis
@kpaizee - could you please give this a Technical Writing review? @arturoherrero - could you please review the EM checklist, as DRI?
requested review from @kpaizee
assigned to @arturoherrero
requested review from @g.hickman
marked the checklist item Follow the process to create a deprecation YAML file. as completed
- Resolved by Kati Paizee
@alexkalderimis There is a pipeline failure that seems easy to fix.
added breaking change label
marked the checklist item If the deprecation is a breaking change, add label
breaking change
. as completedadded 1 commit
- 8e88762a - Add deprecation notice for GlobalID compatibility layer
- Resolved by Alex Kalderimis
- Resolved by Alex Kalderimis
- Resolved by Alex Kalderimis
- Resolved by Alex Kalderimis
- Resolved by Alex Kalderimis
- Resolved by Alex Kalderimis
- Resolved by Alex Kalderimis
- Resolved by Alex Kalderimis