Changelog

We maintain automatically generated changelog pages with user-facing change descriptions for Tenzir Node and Tenzir Platform.

The source for these generated pages is a set of Markdown files located within the /changelog directory of this repository.

• Directorychangelog

  • Directorynode

    • Directorynext

      • 0195fc99-14a9-79d0-bc25-9f81d405f096.md
      • 0195fc9d-815f-71e2-b372-08811f4834e5.md
    • Directoryv5.0.0

      • 0195fc9d-cb72-7f51-88b9-20adff54aadb.md
  • Directoryplatform

    • Directorynext

      • 0195fc9d-ebde-7020-b312-72b405c50742.md

Each product (node, platform) has subdirectories for each version (e.g., v5.0.0), with next referring to the currently unreleased version accumulating changes on the main branch. Within each version directory exists a set of .md files representing individual changelog entries.

The basename of every file is a UUID v7. Because the first 48 bit encode a Unix timestamp, the changelog entries are implicitly sorted by time.

Here’s an example of you can generate a UUID v7:

❯ cargo install kodumaro-uuid-cli
❯ uuid v7
urn:uuid:0195fc9b-a69c-72e3-b91c-4a00ee6f49c6

Changelog Entry Format

Each individual changelog entry must be a Markdown file (.md) structured with YAML frontmatter followed by the description of the change.

A changelog has the following structure:

---
title: Concise Title of the Change  # Required
type: feature                       # Required: 'feature', 'change', or 'bugfix'
authors: [github_username]          # Required: GitHub username(s) (or use 'author')
prs: [1234]                         # Optional: GitHub PR number(s) (or use 'pr')
---

Detailed description of the change using Markdown, focusing on the user impact.
Explain what changed, why, and how users might interact with it.

The frontmatter supports these fields:

• title (Required): A concise title describing the change. This will appear as a heading (###) in the generated changelog page for that version.
• type (Required): The category of the change. This determines which section the entry appears under (“Features”, “Changes”, or “Bug Fixes”). Must be one of:
  • feature: For new functionality.
  • change: For modifications to existing functionality.
  • bugfix: For bug fixes.
• authors / author (Required): The GitHub username(s) of the author(s). Provide a single username as a string or multiple usernames as a YAML list ([user1, user2]). You can use either author or authors for a single author, but prefer authors for lists. Do not use both author and authors in the same file, as this will cause an error. The script generates links like [@username](...).
• prs / pr (Optional): The relevant GitHub Pull Request number(s). Provide a single number or multiple numbers as a YAML list ([123, 456]). You can use either pr or prs for a single PR number, but prefer prs for lists. Do not use both pr and prs in the same file, as this will cause an error. The script generates links like [#123](...) for products configured with a pr_base_url (currently enabled for node).

Below the closing --- of the frontmatter, write the description using standard Markdown.

Focus on the user

Explain the change from their perspective. What is the impact? How does it affect usage or behavior? Examples go a long way. Be clear and concise.

Adding an Entry Manually

If you have written a changelog entry file (.md) according to the format above, here’s how to add it to the tenzir/docs repository:

1. Clone the Repository: If you haven’t already, clone the tenzir/docs repository:

   git clone git@github.com:tenzir/docs.git
   cd docs

2. Navigate to the Correct Directory: Change into the appropriate product and version subdirectory within the changelog/ directory. Use next for unreleased changes going into the next version.
   • Example (Upcoming Node feature): cd changelog/node/next/
   • Example (Platform v1.2.0 fix): cd changelog/platform/v1.2.0/
3. Place Your File: Copy or move your new .md changelog entry file into this directory.
4. Commit and Push: Stage the new file, commit it, and push it to the main branch (or the relevant branch if targeting a specific release).

   git add <your-changelog-file>.md
   git commit -m "Add changelog entry for <brief description>"
   git push origin main

Adding an Entry via CI from another Repository

Changelog entries related to changes in other repositories (like tenzir/tenzir) can be automatically added to this docs repository via GitHub Actions in the source repository.

The CI workflow in the source repository (e.g., tenzir/tenzir) needs to perform these general steps:

1. Generate Entry: Create the content of the .md changelog file (frontmatter + description) based on the change (e.g., from PR metadata). Ensure it follows the Changelog Entry Format.
2. Checkout docs Repo: Use actions/checkout to check out the tenzir/docs repository into a separate path. This requires a token or deploy key with write permissions to tenzir/docs, stored as a secret in the source repository.
3. Create File: Create the new .md file within the checked-out docs repository structure at the correct path (changelog/<product>/<version>/<filename>.md). The <version> should typically be next.
4. Commit and Push: Use git commands within the workflow to:
   • Configure the git user (user.name, user.email).
   • Stage the newly created file (git add).
   • Commit the file (git commit -m "Add changelog for <feature/fix> from <source-repo> [skip ci]"). Remember to include [skip ci] in the commit message to prevent CI loops.
   • Push the commit to the main branch of tenzir/docs.

For a concrete example of checking out and pushing to the docs repository using a secret token, refer to the Documentation workflow within the tenzir/tenzir repository.

Publishing Process

Once a new changelog entry (.md file) lands on the main branch of the tenzir/docs repository, whether added manually or via CI from another repo, a GitHub Actions workflow executes the changelog.py script located in the /changelog directory. The script performs the following actions:

1. Aggregates all .md entries for each product and version.
2. Generates the corresponding versioned .mdx pages within the mdx/changelog/ directory (e.g., mdx/changelog/node/next.mdx, mdx/changelog/node/v5-0-0.mdx). The output directory can be configured via the --output-dir flag (defaulting to mdx).
3. Generates or updates the index.mdx file within each product’s generated changelog directory (e.g., mdx/changelog/node/index.mdx) with sorted links to the version pages.
4. If the --sidebar-file flag is used in the workflow, it generates or updates the specified TypeScript sidebar file (defaulting to sidebar-changelog.ts).
5. Commits these generated/updated files back to the main branch with a [skip ci] message.

The deployed documentation site is built using the contents of the repository after these generated files are committed, ensuring the latest changelogs are always published.