> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zapier.com/llms.txt
> Use this file to discover all available pages before exploring further.

> Generate a release changelog for a new version of the Zapier Platform. Use when the user asks to create a release changelog, version announcement, or release notes for a new platform version.

# SKILL

# 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`):

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```mdx theme={null}
---
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:

```bash theme={null}
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