Update version-specific changes styleguide

Achilleas Pipinellisrequested to merge
axil-update-version-specific-changes-styleguide into master

What does this MR do?

Rewrites the styleguide for version-specific upgrade notes to make the upgrade notes pages easier to parse, update, and link to.

The existing styleguide at doc/development/documentation/topic_types/version_specific_changes.md is replaced with a new structure. The page is renamed to "Upgrade notes style guide."

Problems with the current upgrade notes pages

  • Items are mixed into bullet lists under each version heading. Admins have to read every bullet to figure out if it applies to them.
  • Installation-method subsections (### Linux package installations, ### Geo installations) repeat on every version, producing unstable auto-numbered anchors that shift when new versions are added.
  • Bullet points are not linkable. Support cannot link to a specific item within a version section.
  • No consistent structure per item. Some items are one-liners, some are paragraphs with tables. Contributors don't know where to put things.
  • Bugs spanning multiple versions are handled inconsistently: sometimes repeated in full, sometimes mentioned once, sometimes linked.
  • No clear rule for cross-major-version issues.

Key structural changes

Two-layer page structure

Each upgrade notes page now has two distinct parts:

  • Version indexes at the top: lightweight lists of links, one per minor version, that admins scan to find what affects their upgrade.
  • Upgrade notes at the bottom: the actual content for each item, each with its own H3 heading and stable anchor.

Version indexes

  • Use ## Upgrades to X.Y headings (minor version only, no patch headings).
  • Each index line includes a patch version prefix in parentheses and links to the upgrade note: - (18.2.3) [Title](#anchor).
  • Items listed in descending patch order within each version index, so the most recent items appear first.
  • Installation method tags at the end of index lines for non-universal items: (Geo), (Linux package), (Docker). Items affecting all methods get no tag.
  • Multi-version items appear in each relevant version index linking to the same anchor.

Upgrade notes

  • Every item gets its own H3 heading with a descriptive title. No version numbers in headings.
  • Metadata lines (Versions, Affects) as a plain list directly under the heading, immediately visible without expanding.
  • Details blocks used only for tier/offering on Geo items (established GitLab docs pattern).
  • Multi-version items include an affected-releases table with Release / Affected patch levels / Fixed patch levels columns.
  • Complex items use H4 sub-headings for internal structure.

Page layout changes

  • The "Issues to be aware of when upgrading from" section is merged with the Upgrades to X.0 index, since they're answering the same question: "what do I need to know when I arrive at X.0?".
  • Installation-method subsections are replaced by the "Affects" metadata line on each item and the installation method tag in the index.

Other guidance

  • Required stops documented with alert blocks in the version index, including conditional stops with check queries.
  • Cross-major-version issues documented on the newer page, linked from the older page.
  • Continuations of previous version items link back instead of repeating context.

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 Achilleas Pipinellis

Merge request reports