PostHog Handbook Library / Wizard And Docs

1,107 words. Estimated reading time: 5 min.

# 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.

### Internal Slack channel

We run an internal Slack channel that surfaces what we ship. We recommend that everyone at PostHog joins it.

| Channel | Use it for | Cadence | Owner | |---------|------------|---------|-------| | `#changelog` | What's just shipped | Updates constantly as PRs merge | |

The channel is powered by agentic workflows that scan merged PRs and feature flag changes in the `posthog/posthog` repo, classify them, and summarize them into it, posting each impactful change as it lands.

You can also opt a PR into the workflow manually:

- PR template checkbox — the `posthog/posthog` PR template has a Publish to changelog? checkbox under Automatic notifications. Tick it when you want to override the automated classification.
- `@posthog` Slack app — you can also include or exclude PRs from these workflows via the `@posthog` Slack app, which is handy after the fact (e.g. once a change is in production).

<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 that filters entries from the main changelog. You can also publish directly from these pages 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 | | AI Observability | /docs/ai-observability/changelog | | Feature Flags | /docs/feature-flags/changelog | | ... | ... |

##### Adding a changelog page for a new product

These pages filter the main changelog by Strapi labels, so adding one takes three changes in the posthog.com repo — all three are required:

1. Add `contents/docs/<product>/changelog.mdx` rendering ``.
2. Add a `/docs/<product>/changelog` link to the product's sidebar in `src/navs/index.js`.
3. Add an entry for the product to `productConfigMap` in `src/components/Docs/ProductChangelog.tsx`, mapping it to the topic and team names used in Strapi.

Step 3 is the one people forget, so CI fails if a page is missing it. The same applies when a topic or team is renamed in Strapi — update `productConfigMap` to match, or the page goes empty.

### Links and resources

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

Canonical URL: https://posthog.com/handbook/wizard-and-docs/how-to-publish-changelog

GitHub source: contents/handbook/wizard-and-docs/how-to-publish-changelog.mdx

Content hash: `83c338648ed83269`

Static reader notes

- `MDX_COMPONENT_STATIC_ADAPTER`: Adapted interactive MDX components for static reading: CalloutBox, Caption, PrivateLink, ProductChangelog, ProductScreenshot, ProductVideo, SmallTeam.