Skip to main content

​
Release Changelog Generator

This skill creates a release changelog entry in integrations/news/2026/ for a new version of the Zapier Platform.

​
Overview

When invoked, this skill will:
  1. Fetch commits from a specified range (or auto-detect from last git tag)
  2. Extract PR numbers from commit messages
  3. Fetch PR details from GitHub using gh CLI
  4. Categorize changes into cli/core/schema/misc sections
  5. Categorize changes into cli/core/schema/misc sections and assign a change type label
  6. Generate a formatted .mdx file in integrations/news/2026/v{version}.mdx
  7. Run pnpm run render-news to update aggregated pages

​
Instructions

​
Step 1: Get Version from User

The user will provide the version number they want to release (e.g., “18.1.1”). This is typically passed as an argument when invoking the skill. Do NOT ask the user for a commit range - auto-detect it from the previous semantic version.

​
Step 2: Auto-Detect Commit Range from Previous Version

The zapier-platform repo uses tags in format zapier-platform-core@{version}. Auto-detect the previous version:
  1. Parse the requested version (e.g., “18.1.1” → major=18, minor=1, patch=1)
  2. Calculate previous version:
    • If patch > 0: previous = major.minor.(patch-1)
    • If patch == 0 and minor > 0: previous = major.(minor-1).x (find highest patch)
    • If minor == 0: previous = (major-1).x.x (find highest minor.patch)
  3. Run this in the zapier-platform repo (typically at ~/ws/zapier/zapier-platform): 
cd ~/ws/zapier/zapier-platform && git fetch --tags
git log zapier-platform-core@{previous-version}..zapier-platform-core@{new-version} --oneline
Example: For version 18.1.1, the previous version is 18.1.0, so use: 
git log zapier-platform-core@18.1.0..zapier-platform-core@18.1.1 --oneline
Important: The zapier-platform repo is separate from public-api-docs. Make sure to cd into it first.

​
Step 3: Extract Commits and PRs

Get all commits in the range — do NOT use --no-merges and do NOT filter by directory: 
git log <commit-range> --oneline
Merge commits contain PR numbers in the format Merge pull request #1234 from .... Extract all PR numbers from these. Exclude PRs that are:
  • Release PRs (e.g., “release 18.2.1”)
  • Version bump commits from pnpm bump
  • Legacy-scripting-runner-only changes (those belong in the LSR changelog, not the platform changelog)

​
Step 4: Fetch PR Details from GitHub

For each PR number found, fetch details using gh CLI: 
gh pr view <PR_NUMBER> --json title,body
From the PR title and body, determine the change type and category. Change type — use a text label prefix:
  • [fix] — bug fixes (contains “bug”, “fix”)
  • [feature] — genuinely new capabilities (new field type, new API, new command). Must introduce something that didn’t exist before.
  • [polish] — improvements to existing features (better output, clearer labels, UX tweaks). If a PR improves or clarifies something that already worked, it’s [polish] not [feature].
  • [docs] — documentation-only changes (doc updates, help text improvements, README changes)
  • [chore] — maintenance and dependency bumps (default, includes security updates)
  • [breaking] — breaking changes (contains “breaking”)
  • Category (cli/core/schema/misc):
    • cli - mentions “cli”, “command”, or touches packages/cli
    • core - mentions “core”, “middleware”, “runtime”, or touches packages/core
    • schema - mentions “schema”, “type”, “definition”, or touches packages/schema
    • misc - everything else (dependencies, docs, tooling)

​
Step 5: Generate Description

Auto-generate a description that specifically names the key changes. Avoid generic phrases like “New features and bug fixes” — be concrete but brief. Examples:
  • “JSON input field type, versions command improvements, function-based dynamic dropdown fix”
  • “Custom middleware hooks, build performance improvements”
  • “Security fix for zip extraction vulnerability”
  • If there are breaking changes: “Breaking: Node.js 24 runtime, new authentication model”

​
Step 6: Create the MDX File

Generate the file at integrations/news/2026/v{version}.mdx with this structure: 
---
title: What's changed in v{version}
description: {auto-generated description}
icon: newspaper
---

_Released: {YYYY-MM-DD}_

{Introductory paragraph summarizing the release}

{For minor/major releases with a headline feature: add a short usage example
(code snippet) demonstrating the feature, followed by a link to the relevant
documentation page on docs.zapier.com. The doc link format is
`/integrations/build-cli/<page>#<anchor>`. This helps developers immediately
understand the new capability without leaving the changelog.}

## cli

- [type] {PR title} ([#{number}](https://github.com/zapier/zapier-platform/pull/{number}))
...or "None!" if no CLI changes

## core

- [type] {PR title} ([#{number}](https://github.com/zapier/zapier-platform/pull/{number}))
...or "None!" if no core changes

## schema

- [type] {PR title} ([#{number}](https://github.com/zapier/zapier-platform/pull/{number}))
...or "None!" if no schema changes

## misc

- [type] {PR title} ([#{number}](https://github.com/zapier/zapier-platform/pull/{number}))
(Only include this section if there are misc changes)

​
Step 7: Run Render Script

After creating the file, run: 
pnpm run render-news
This will update:
  • integrations/news.mdx (main news page)
  • integrations/news/single-page.mdx (single page view)
  • integrations/news.xml (RSS feed)
  • integrations/news/2026/index.mdx (year index)

​
Step 8: Provide Next Steps

Tell the user: 
Created changelog: integrations/news/2026/v{version}.mdx

Next steps:
1. Review the generated file and edit if needed
2. Preview locally with: pnpm run dev
3. Commit the changes when ready

​
Important Notes

  • Use [type] text labels ([fix], [feature], [polish], [docs], [chore], [breaking]) to prefix each entry, not emoji
  • Include PR links in the format ([#123](https://github.com/zapier/zapier-platform/pull/123))
  • Group related PRs together - if multiple PRs are for the same change (e.g., dependabot bumping lodash across multiple packages), list them all on one line: - [chore] Bump lodash from 4.17.21 to 4.17.23 across the board ([#1228](url), [#1229](url), [#1230](url))
  • Use “None!” literally if a section has no changes (see examples in integrations/news/2026/)
  • Get today’s date for the _Released: line in YYYY-MM-DD format
  • Follow existing patterns - read a recent changelog like integrations/news/2026/v18.1.0.mdx for reference

​
Example Reference Files

Look at these existing changelogs for format examples:
  • integrations/news/2026/v18.1.0.mdx - typical minor release
  • integrations/news/2026/v18.0.7.mdx - release with bug fixes
  • integrations/news/2025/v18.0.0.mdx - major release with breaking changes

​
Troubleshooting

  • If gh CLI is not available, inform the user they need to install it: brew install gh
  • If commit range is invalid, verify with git log <range> first
  • If no PRs found, check that commits include PR references in format (#1234)
  • If render-news fails, user can run it manually: pnpm run render-news
  • If zapier-platform repo not found at ~/ws/zapier/zapier-platform, ask user for the correct path
  • If tags not found, run git fetch --tags in the zapier-platform repo first