Skip to content

Add migration for version history

Sarah German requested to merge 11-history-migration into main

What does this MR do and why?

Migrates version history to the Hugo shortcode version.

Closes #11 (closed)

How to set up and validate locally

  1. Configure a local GitLab Docs environment: https://gitlab.com/gitlab-org/technical-writing-group/gitlab-docs-hugo/-/blob/main/doc/setup.md.
  2. Checkout this branch
  3. Fetch up-to-date content, but don't run any migrations: REMOVE_BEFORE_CLONE=true go run cmd/gldocs/main.go clone
  4. Run this migration only: go run cmd/gldocs/main.go migrate history ../gitlab/doc
  5. View the diff: git -C ../gitlab diff

Expected result: History items (blockquotes, with list items, that contain specific keywords) are rewritten as Hugo shortcodes, like this:

Before:

> - Introduced in 15.0
> - Deprecated in 17.0

After:

{{< history >}}

- Introduced in 15.0
- Deprecated in 17.0

{{</ history >}}
  • Multiple history items on consecutive lines should be grouped into a single {{< history >}} block
  • Blockquote markdown character (>) is dropped

We can also test the end-to-end build with the migration:

  1. Run the full build process: REMOVE_BEFORE_CLONE=true make clone-docs-projects (runs the initial clones + all migrations)
  2. Run the preview server: make view
  3. Browse around the site and verify that the History content matches its appearance on the existing site.

Example pages:

Merge request acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Sarah German

Merge request reports