Documentation
How-to Guides
Writing Changelog articles

Writing Changelog articles

Introduction

This guide explains how to write clear, customer-friendly changelog articles. Changelog articles are how we communicate updates to customers and the wider public. They can cover company announcements, new features, post mortems and maintenance work. In all cases, the goal is the same: make it easy for readers to understand what changed, why it matters and what (if anything) they need to do.

Pre-requisites

Have access to the skyscrapers/documentation repository.

Step-by-step

  1. Configure the front-matter section:

    ---
title: "Changelog article title"
changelog_categories: Announcements
date: 2026-01-01 11:11:11 +0100
---

    In the front matter you define:

    • a title
    • a changelog category (Announcements, Kubernetes, New Features)
    • tags (optional)
    • the publication date

  2. Below the front matter, add the article content itself. Use Markdown and avoid HTML where possible.

Verify

  • (Optional) Run Hugo locally and preview the article in your browser.
  • Create a pull request and ask a colleague to review the article.
  • The expected result is a readable article with a clear title, category, date and content.

Additional notes

  • When merging your PR, ensure the date is set correctly so the article appears at the top of the changelog as the most recent entry.
Last updated on
Tailscale setup