Deprecate post: Global IDs in work items route

Be sure to link this MR to the relevant deprecation issue(s).

• Deprecation Issue: #393836 (closed)

If there is no relevant deprecation issue, hit pause and:

• Review the process for deprecating and removing features.
• Connect with the Product Manager DRI.

Deprecation announcements can and should be created and merged into Docs at any time, to optimize user awareness and planning. We encourage confirmed deprecations to be merged as soon as the required reviews are complete, even if weeks ahead of the target milestone's release post. For the announcement to be included in a specific release post and that release's documentation packages, this MR must be reviewed/merged per the due dates below:

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: @gweaver - Required
• Engineering Manager: @donaldcook - Required
• Technical writer: @msedlakjakubowski - Required

By 11:59 AM PDT 15th: EM/PM assigns this MR to the TW reviewer for final review and merge: @EM/PM

By 11:59 PM PDT 17th: TW Reviewer updates Docs by merging this MR to master: @TW

---

Please review:

• The definitions of "Deprecation", "End of Support", and "Removal".
• The guidelines for deprecations.
• 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.
• Confirm this MR is labeled release post itemdeprecation
• Follow the process to create a deprecation YAML file.
• Add reviewers by the 10th.
• Add scoped devops:: and group:: labels as necessary.
• Add the appropriate milestone to this MR.
• When ready to be merged (and no later than the 15th) @mention 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 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.
• Dates:
  • Make sure that the milestone dates are based on the dates in Product milestone creation.
• 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:

1. Check out the MR's branch (in the gitlab-org/gitlab project).
2. 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 run bin/rake gitlab:docs:check_deprecations to verify that the doc is up to date.
3. Commit the updated file and push the changes.
4. 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.

changed milestone to %15.10

added GitLab Free GitLab Premium GitLab Ultimate Technical Writing breaking change deprecation devopsplan groupproject management maintenancerefactor release post release post item release post itemdeprecation sectiondev typemaintenance labels

assigned to @donaldcook, @gweaver, and @msedlakjakubowski

@mcelicalderonG thanks for adding the breaking change label!

This merge request introduces breaking changes. Learn more about breaking changes.

It's important to identify how the breaking change was introduced. To estimate the impact, try to assess the following:

• Are there existing users depending on this feature?
  • Are self-managed customers affected?
  • To verify and quantify usage, use Grafana or Kibana.
  • If you're not sure about how to query the data, contact the infrastructure team on their Slack channel, #infrastructure-lounge
• Was sufficient time given to communicate the change?
• Changes in the permissions, the API schema, and the API response might affect existing 3rd party integrations.
  • Reach out to the Support team or Technical Account Managers and ask about the possible impact of this change.

This message was generated automatically. You're welcome to improve it.

unassigned @msedlakjakubowski

requested review from @msedlakjakubowski

added documentation label

	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 (Link to current live version)

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 🚫 Danger

@mcelicalderonG @donaldcook @gweaver Hi! Just making sure - isn't it too late to introduce a deprecation to be removed in 16.0? The handbook says we need at least 3 milestones, and specifies 15.9 as the last one in this cycle (I confirmed it with Brian Rhea before he left).

@mcelicalderonG I left some suggestions for style and formatting. I'll continue this tomorrow and review the message body.

added docsfeature twdoing workflowin review labels

added 1 commit

• f894be21 - Docs review suggestions

Compare with previous version

added 1 commit

• 2bf1afe0 - Deprecate post: Global IDs in work items route

Compare with previous version

mentioned in merge request !114640 (merged)

mentioned in issue gitlab-com/Product#5541 (closed)

added 1 commit

• cacdc942 - Apply 1 suggestion(s) to 1 file(s)

Compare with previous version

added 1 commit

• 50c30153 - Apply 1 suggestion(s) to 1 file(s)

Compare with previous version

added 1 commit

• 79549c3d - Apply 1 suggestion(s) to 1 file(s)

Compare with previous version

unassigned @donaldcook

I'm not sure why I can't approve this MR, so please take this comment as my approval!

/cc @msedlakjakubowski

assigned to @donaldcook

FYI I'll rebase and regenerate the doc.

added 592 commits

• 79549c3d...4c69b130 - 588 commits from branch master
• 6c80972a - Deprecate post: Global IDs in work items route
• 94185c85 - Apply 1 suggestion(s) to 1 file(s)
• 676bfe10 - Apply 1 suggestion(s) to 1 file(s)
• 39e5721a - Apply 1 suggestion(s) to 1 file(s)

Compare with previous version

added 13 commits

• 39e5721a...48812acb - 8 commits from branch master
• 00ba36fe - Deprecate post: Global IDs in work items route
• 43ee06d6 - Apply 1 suggestion(s) to 1 file(s)
• ac3f4861 - Apply 1 suggestion(s) to 1 file(s)
• 4dad979e - Apply 1 suggestion(s) to 1 file(s)
• fc253cc8 - Regenerate deprecation doc

Compare with previous version

approved this merge request

👋 @gweaver, thanks for approving this merge request.

This is the first time the merge request is approved. To ensure full test coverage, a new pipeline will be started shortly.

For more info, please refer to the following links:

• rspec predictive jobs
• jest predictive jobs
• merging a merge request.

added pipeline:mr-approved label

unassigned @gweaver

added 182 commits

• fc253cc8...effdfd05 - 181 commits from branch master
• 93322827 - Deprecate post: Global IDs in work items route

Compare with previous version

resolved all threads

added Pick into 15.10 label

marked the checklist item Required review and approval: Technical Writer designated to the corresponding DevOps stage/group. as completed

approved this merge request

enabled an automatic merge when the pipeline for 00526efe succeeds

merged

mentioned in commit a5f495e5

added workflowstaging-canary label and removed workflowin review label

added workflowcanary label and removed workflowstaging-canary label

added workflowstaging label and removed workflowcanary label

added workflowproduction label and removed workflowstaging label

added workflowpost-deploy-db-production label and removed workflowproduction label

Hey @mcelicalderonG, @msedlakjakubowski 👋

Starting with 15.10, there is a new engineering process for patch releases so the Pick into 15.10 label will not have any effect. For this merge request to be included in the next patch release for 15.10, a backport has to be created and merged into the 15-10-stable-ee branch. Please refer to the runbook for guidelines and take a look at the announcement issue for more details.

Feedback and questions welcome, you can drop them on the announcement issue or on the #releases slack channel.

@msedlakjakubowski do we need to backport this docs only change? The change is already published in our docs at https://docs.gitlab.com/ee/update/deprecations.html#work-items-path-with-global-id-at-the-end-of-the-path-is-deprecated

@mayra-cabrera Thanks! I missed the change 🙇

@mcelicalderonG Maybe not. I guess the online version of the page is SSOT for deprecations.

FYI @gweaver

mentioned in issue gitlab-com/gl-infra/delivery#2890 (closed)

removed Pick into 15.10 label

added releasedcandidate label

added releasedpublished label and removed releasedcandidate label