Skip to content

Clarify language around deprecations and removals

Marcel Amirault requested to merge update-deprecations-removals-language into master

What does this MR do?

In !107457 (merged), we updated the language in the deprecation/removal templates to focus less on the "deprecation" and "removal" terminology. That made it clearer that these entries could be other types of announcements that are not deprecations or removals. We also have changing defaults, added/changed limits, updated CI/CD templates, and other behavior changes that we need to announce, usually due to being a breaking change.

We should align the language in the main page as well, because we end up with sections like this:

## Removed in 15.4

### SAST analyzer consolidation and CI/CD template changes

## Removed in 15.0

### API: `stale` status returned instead of `offline` or `not_connected`

I don't believe it's accurate to say "Removed in" for these "non-removal" breaking changes. But if we change to Changed in 15.4, it'll work for all types of announcements on this page.

This is similar to the language update in Pared down language and added Announced in (!88476 - merged), where we started using Announced in for the deprecations, which also works for all types of announcements.

I've also updated the intro sections for both pages to reflect the nature of the content on the pages.

SEO

A separate issue is that if you are interested in upgrading and searching the site for a breaking changes list, the search term breaking changes does not list this page in the first results:

If you scroll down and eventually find the page, it's not clear that this is the correct page. Is the "removals" page the one that lists the breaking changes?

Adding Breaking changes to the title (# Removals and breaking changes by version) should help with the SEO issue and make sure people are landing on the correct page. I think this is important to do now, before 16.0, as we'll have a flood of people looking for these details when 16.0 is released.

Review apps

Related issues

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.
Edited by Marcel Amirault

Merge request reports