At the moment, we release a new version every month (unless it makes sense not to!). This might change in the future.
Every month we bump the
major.minor.patch. At the moment, we're at version 1 for major. This will only change once we have released sufficient functionality under stage 2 of our Roadmap.
Hopefully we will not have to do many patch versions, but if between versions we discover a breaking bug, we will.
💡 For the context of this guide
[version]is interpreted as the version of the release (e.g.
On the week before the release, on Friday, we institute a code freeze. We branch master into release-[version] and deploy that to our playground environment (playground.posthog.com) and ClickHouse test environment (samltest.posthog.net). Only bugfixes are allowed to be merged into this branch (and thus put on production) between the code freeze and the release going out. This gives us about three days to test if this release has any bugs.
⚠️ As soon as the branch is created and pushed to GitHub, the Docker image will be built and pushed to Docker Hub under the tag
- Start the
release-[version]branch to initiate the code freeze.
- Figure out what's updated in this release with the command below. The command will output the entire commit list to
log.txt. You can use this list to obtain external contributions to highlight in the Array.git checkout release-[version]git log --pretty=format:"%s %ae" [old-version]..head > log.txt
- Write up the main fixes/improvements and breaking changes into
CHANGELOG.mdfollowing the structure of the previous releasegit add CHANGELOG.mdgit commit -m "Changelog version 1.29.0"
- Update the
posthog/version.pygit checkout release-[version]git add posthog/version.pygit commit -m "Bump version [version]"
- Deploy PostHog playground from the
release-[version]branch on Heroku dashboard.
- Deploy ClickHouse test environment from the
- Break the release session! It's imperative that the session uses the published
release-[version]-unstableimage from Docker Hub (this is published automatically using GitHub Actions), to avoid any potential bugs creeping up in the final build stage.
- Write up the PostHog Array blog post
- Edit the Helm Chart:
appVersionto the latest app version (same number as on the Docker image).
- Change the docker tag in values.yaml to point to the new tag (e.g.
- Push the relevant changes and add the
bump-minorlabel to the PR. Do not merge until the latest version is built.
- Tag the version in GitHub. This will also build and push the
latest-release(for both PostHog base & FOSS) Docker images to Docker Hub. Please do this once the release is completely ready, some users may see the image on Docker Hub and update immediately.git tag -a [version] -m "Version [version]"git push origin head --tags
- Cherrypick the commits for the changelog and
version.pyinto a new PR (branch
[version]-sync) to make sure
masteris up to date.
- Update the
versions.jsonfile and add the new release information (release name and release date). Merging this to master will notify users that an update is available.
- Update the
- Go to the EWXT9O7BVDC2O Cloudfront distribution to the "Invalidations" tab and add a new one with
/*value. This will refresh the Cloudfront cache so that users can see the new version.
- Post a message on the PostHog Users Slack (community) in #general to let everyone know the release has shipped.
- Send the newsletter with the PostHog Array. We do this through Mailchimp. You can use the template for the previously sent newsletter. You may need to ask someone with access to help with this last part.