How to publish changelog

We have one of the coolest changelogs on the internet. It's also one of the busiest.

As a company that ships weirdly fast, it's important to share what we're working on with as many people as possible, as often as possible. The changelog is a great way to do that.

<ProductVideo videoLight="https://res.cloudinary.com/dmukukwp6/video/upload/changelog_handbook_1_8038f2d9d4.mp4" autoPlay={false} muted={false} loop={false} background={false} alt="The /changelog page on the website" classes="rounded" />

The /changelog page on the website

Changelog content and ownership

Technically speaking, the changelog is a stream of content that's published across multiple channels.

From start to finish, a changelog entry is:

1. Posted in the #changelog Slack channel
2. Published on the website by
3. Produced into a video by
4. And then sent in an email by

The engineer is responsible for making sure their feature appears in the #changelog Slack channel and writing the initial draft (details below).

This page mainly covers the first two steps.

The changelog code and data (stored in our Strapi CMS) is mainatined by the . To learn more about how the features work, check out their roadmap and changelog handbook pages.

What gets included

New features! But changelog entries can also include beta launches, UX improvements, or performance improvements.

For engineers, here's the rule of thumb: if you think an update (small or big) is worth sharing with users, it's probably worth posting about in the changelog.

A published changelog entry

How the publishing process works

We have an end-to-end process for moving shipped features into the website changelog.

1. An engineer merges a feat PR into the monorepo or rolls out a feature flag.
2. Relay workflows are triggered, which classify and summarize the PR or flag.
3. The feature is automatically posted in the #changelog Slack channel if classified as "impactful" by the workflow.
4. The PR author or engineer is tagged in the Slack thread.
5. The engineer writes the initial changelog draft (2-3 sentences and screenshots) and replies to the thread.
6. At the end of every week, the team reviews the #changelog channel, compiles the entries, edits them, and then publishes to the /changelog page.

Anyone can manually post in the #changelog Slack channel if something is worth sharing but isn't captured by the automated workflow.

The #changelog Slack channel

How to publish changelog yourself

People are encouraged to self-serve and publish changelog entries. Here's how.

You must be logged into your posthog.com account. Only website moderators (a.k.a PostHog employees) are permitted to publish changelog entries.

Option 1: The main changelog

Go to the /changelog page and click the + button in the top right corner.

<ProductVideo videoLight="https://res.cloudinary.com/dmukukwp6/video/upload/changelog_form_c7f3d3a351.mp4" alt="Changelog form" classes="rounded" />

Fill out the changelog form and click Create to publish. The changelog entry will appear on the website on the next website build, which is usually when a PR is merged into the master branch.

| Field | Required | Recommended value | |-------|----------|-------------------| | Title | Yes | The title of the changelog entry. Keep it short and sweet. | | Description | Yes | The description with native Markdown support. Add screenshots or gifs here. | | Hero image | No | We leave this empty. We add images in the description field for more control. | | Status | Yes | It must be set to Complete to appear in the changelog. | | Date | Yes | The completed date of the changelog entry. | | Team | Yes | The team that shipped the feature. | | Author | No | We normally leave this blank because we pull in GitHub PR metadata which includes author and reviewers. | | Product or feature | Yes | The category or product area of the feature. Select Uncategorized if nothing fits. | | Type | Yes | Set to New feature for most changelog entries. | | GitHub URLs | Yes | It's technically optional, but the GitHub URL populates the changelog entry with the feature's PR metadata. | | Category | Yes | The product category of the changelog entry. | | Show on homepage | No | Always set the toggle to off or no. |

Option 2: The product changelogs

Each product has a dedicated changelog page in their docs. You can also publish from there using the + Add changelog button.

Each product should have a changelog page in their docs

| Product | Changelog page | |---------|----------------| | PostHog AI | /docs/posthog-ai/changelog | | Product Analytics | /docs/product-analytics/changelog | | Session Replay | /docs/session-replay/changelog | | Error Tracking | /docs/error-tracking/changelog | | LLM Analytics | /docs/llm-analytics/changelog | | Feature Flags | /docs/feature-flags/changelog | | ... | ... |

Option 3: Automated drafting via Slack reaction

The team uses an automated flow to draft changelog entries directly from Slack.

1. React with ✅ on an entry in the #changelog Slack channel. We recommend reacting to the top-level message.
2. This kicks off a Relay workflow where Claude writes the draft in the required format – YAML frontmatter for the Strapi fields, and Markdown for the body.
3. The draft opens as a new issue in the changelog-drafts repo.
4. Review the draft in the GitHub issue, edit as needed, then add the publish label when it's ready to go.
5. A GitHub Action POSTs the entry to Strapi. It adds a success or failure label (synced or sync-failed) and comment to the GitHub issue, and self-closes on success.
6. The changelog entry will appear on the website on the next website build.

Because Claude is writing the initial draft, make sure you review the draft in detail before you add the publish label – don't rubber-stamp it.

Links and resources

• Relay workflow for PRs
• Relay workflow for feature flag rollouts
• Relay workflow for automated changelog drafts
• PostHog webhook for feature flag rollouts
• Slack bot for posting in #changelog
• #changelog Slack channel
• Google Doc for editing changelog entries