Change the "Releases" page to "Changelog" and create an archive

[ADubhlaoich]

Overview

As a NGINX Ingress Controller user, I want a shorter release page, So I can quickly navigate recent changes.

As a user of multiple NGINX products, I want consistency, So I can use existing knowledge to navigate any documentation.

Description

Per #6259 and #7669, the NGINX Ingress Controller team is interested in DocOps' perspective on managing release notes. This was an item of discussion within the DocOps team recently.

NGINX Ingress Controller keeps the full context of a given release within its note, which is ideal, but has a single large page tracking every release in perpetuity, which we decided we want to move away from.

Instead, we would like a page per year, with the current year as the "default", with remaining years archived. These archive should be navigable from the release page but not discoverable from through the navigation bar or sitemap.

We would also like the release page to be named "Changelog", which we find closer to traditional software development. This set of changes will be reflected across other NGINX products in the future, so any concerns or improvements that appear during this ticket's effort will be used to improve the consistency of all documentation.

Tasks

• Rename the "Releases" page to "Changelog", and the filename from releases.md to changelog.md
• Update any link references causing errors
• Create a redirect for the release URL to the new changelog URL
• Create an archive folder, with weight lower than the Changelog page
• Move the existing release notes into new files named 20xx-changelog.md within the archive folder
• Add explanatory text at the top of the Changelog page directing users to the archive
• Hide the archive folder

Some additional context for these tasks will be added as a comment to this issue.

All of this work can be handled manually, but once it is place, it can likely be automated.

Acceptance criteria

• The user can find the Changelog page
• The user can find a link to older archives in a prominent location on the Changelog page
• The user only sees releases for the calendar year on the default Changelog page

[github-actions]

Hi @ADubhlaoich thanks for reporting!

Be sure to check out the docs and the Contributing Guidelines while you wait for a human to take a look at this 🙂

Cheers!

[ADubhlaoich]

Updating the page name is straightforward: it's the title field in the frontmatter at the top of a given page.

We name or rename files to match page names in as concise a manner as possible, and maintain an idea of URL as UI.

By default, folder and filename structure defines the URL given by the web server.

Renaming the file means that https://docs.nginx.com/nginx-ingress-controller/releases/ will become https://docs.nginx.com/nginx-ingress-controller/changelog once deployed.

This also means that the archive links will looks as follows: https://docs.nginx.com/nginx-ingress-controller/archive/2024-changelog 2023, and so on.

When running a local Hugo server for development, it will check internal references, and fire an error if a link is broken.

Changing the filename is certain to cause some errors, but they will guide you to which files and lines need to be updated.

Creating a redirect is handled the same way you would in NGINX, since we host documentation with NGINX.

Configuration is managed internally, and I can show you where in an internal channel.

Similarly, "hiding" the archive folder from navigation is a deployment configuration.

[ADubhlaoich]

For the explanatory text, you can probably just use this paragraph verbatim above the heading for the current release.

This page is the changelog for releases in this calendar year. For older releases, see the archive for previous years: 2024, 2023, 2022, 2021.