How to publish changelog
Contents
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.
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:
- Posted in the
#changelogSlack channel - Published on the website by Docs & Wizard TeamDocs & Wizard Team
- Produced into a video by YouTube TeamYouTube Team
- And then sent in an email by Marketing TeamMarketing Team
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
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.
How the publishing process works
We have an end-to-end process for moving shipped features into the website changelog.
- An engineer merges a
featPR into the monorepo or rolls out a feature flag. - Relay workflows are triggered, which classify and summarize the PR or flag.
- The feature is automatically posted in the
#changelogSlack channel if classified as "impactful" by the workflow. - The PR author or engineer is tagged in the Slack thread.
- The engineer writes the initial changelog draft (2-3 sentences and screenshots) and replies to the thread.
- At the end of every week, the Docs & Wizard TeamDocs & Wizard Team team reviews the
#changelogchannel, 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.
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.
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.
| 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 |
| ... | ... |