Track changes to your product with releases

  • Updated

This article will help you:

  • Use changes in your product as points to build an analysis around

In Amplitude, a release represents a change in your product. It can be a major update like the launch of a new feature, a minor patch to fix a small bug, or the launch of an experiment. Releases are shown as a marker in your time-series charts when they occur.

release_line_chart.png

Amplitude automatically creates releases for all customers on paid plans, but you can also create them manually.

Create a release

Automated releases

Amplitude continuously listens for a new value for the amplitude_logo.png Version user property. When a new value is detected, Amplitude automatically creates a release the next day. It applies the following heuristics when creating a new release:
  • A release must follow semantic versioning format: major.minor.patch where .patch is optional. For example, amplitude_logo.png Version = 12345 will not automatically create a release, but amplitude_logo.png Version = 123.45.6 will.
  • Development projects (projects that contain names like "Test", "Development", "Staging," etc.) are excluded from automatic release generation.
  • If you are sending event data server side via Amplitude's HTTP/Batch API, use the app_version user property.

Automated releases will not be created retroactively for backfilled data.

Configure an automated release

You can configure automated release detection in the Release Timeline frame, if you are an admin or manager. Simply click the settings icon to gain access to the Project Settings fly-out panel. Here you can enable or disable automatic release detection and automatic annotation.

Manual releases

If your product does not use semantic versioning, or you are not on one of our paid plans, you can manually create a release from the release timeline, or via the Microscope in a chart.

To create a manual release, click Create Release and fill in the modal that appears:
create_release.png
    • Release name: The name of the release. This is visible on charts and in the Release Timeline view.
    • Version: The amplitude_logo.png Version user property that defines the product change. Amplitude uses this field to show you any new events introduced in the release, via the Release Report. The Version field selected must be an existing value in your data.
    • Description: The product change brought about in the release. This is visible in the Release Timeline view.
    • Release date: The date the release was shipped.
    • End date: The end date of the release rollout.
    • Platform(s): The amplitude_logo.png Platform(s) this release applies to.
    • Visibility: Whether the release is visible on all charts or not.

Releases API

Releases can also be created programmatically by using the Releases API. This allows you to integrate the creation of releases into your own internal deployment processes.

Edit a release

Releases that have been manually created or automatically detected can be edited to add additional context and information to the release. To do so, open the release from within the release timeline view and click Edit.

By default, all releases are visible across all charts. You can toggle the visibility of a release from the release report page (this view), or the release timeline view.

The release report

From the release timeline, you can click on a release to view the release report. A release report is a collection of metadata and analysis, generated by Amplitude.
In the Metrics section, you can see the number of unique users who have been exposed to your release, and the percentage of your active user base that figure represents. The percentage of active users is the number of users that have seen the version of the release, divided by the number of users on the platform specified in the release definition.
 
release_report.png
 
If new events were included in that release, Amplitude shows them in the table to the right of Metrics. The % Active metrics shows you the percentage of your active user base who are triggering the new events detected since the release date.
 
The Adoption section shows a time series depicting adoption of your release since its launch date. The time series is limited to 30 days since the start of the release.
 

Add items to a release

You can link to other Amplitude content via the Analyses section. This makes it easy for others in your organization to understand how the experiences you've launched have performed, and the impact they've had on your users.

Use releases to distribute both context and outcomes across your team.

To attach items to a release, click + Add Item in the Analyses section of the Release Report.

add_analyses_items.png

The release timeline

The release timeline serves as a living history of all the product updates your team has shipped. It's a chronology of the releases Amplitude has automatically created, and the ones that have been manually added by your team.
 
To access the release timeline, follow these steps:
  1. Navigate to settings.png> Organizational settings > Projects.
  2. Find the project you're interested in and click it.
  3. Open the Releases tab.
NOTE: Currently, the release timeline feature only populates new versions in real time. When backfilling historical data, these releases are not considered new, as they happened in the past. Any backfilled releases can only be added manually to the timeline.