A typical workflow in Amplitude Data

This guide describes your and your team's typical workflow once you've outgrown the main branch. It distills best practices and approaches often seen in customer deployments, and is intended to help you navigate on your own journey.

Create a branch

Working with branches becomes relevant when more teams get involved with Amplitude Data and allowing them to work in isolation becomes critical. Branches also become useful as your tracking plan definition process matures to include formal reviews and approvals.

For example, imagine the product team is launching a new feature. Engineering has already created a new branch in Git, and your product manager is about to spec out corresponding changes to the product's tracking plan.

This is a great time to create a new branch in Amplitude Data as well. Just as engineering is using a Git branch to work "on the side", you're using an Amplitude Data branch to work "on the side" on your tracking plan. The two branches will co-exist for almost exactly the same time and be linked: engineering will pull analytics code from the Amplitude Data branch into their Git branch throughout the feature's development.

TIP: It helps to keep the names of the Git branch and the Amplitude Data branch the same, but it's not a requirement.

Define events

The first step in updating your tracking plan is figuring out what you want to track about your new feature in the first place. What does success look like? What metrics will your feature affect, and what events do you need to collect to calculate those metrics?

Creating events and properties in a branch works just like it does on main. Read more about creating events in Amplitude Data.

When you're done with your first draft and are ready for engineering to take a look, publish a new version. You'll publish a lot of versions as you iterate on your plan with the team, so don't hesitate to publish early and often.

TIP: Changes you make to your branch can't be instrumented until you've published a new version. This means you can safely work in your branch and only release changes to developers when you're ready.

Instrument events

If you haven't already, invite the developers working on the feature to Amplitude Data and ask them to review your proposed plan so far. Does it make sense?

TIP: To see all the changes you've made to your branch, click Merge. If you don't see the Merge button, make sure you've published all your pending changes (you’ll see the Publish button instead if you haven't) and that your branch is up to date with main (you’ll see the Refresh button instead if it isn't).

Next, engineers will start implementing the updated tracking plan in their branch. They'll use the Ampli CLI to generate a new tracking library that matches the changes in the Amplitude Data branch (ampli pull -b {branch-name}).

What issues do they encounter? What's easy and hard for them? It's normal to iterate on your tracking plan with your developers. Publish new versions as needed and as your understanding evolves based on their feedback.

TIP: To keep your branch's tracking plan in sync with the source code, ask your developers to report their status with ampli status -u. You'll see which events have been instrumented, which are out of date, and which are still TBD. Only merge your changes into main once all checkmarks are green.

Request reviews

Once the feature team is happy with the changes—the plan is comprehensive and engineering was able to implement it correctly—your branch is ready for review by other stakeholders.

TIP: Be sure to refresh your changes from main to get your branch up to date and resolve any potential conflicts. You may do this more than once as your developers refresh their branch as well (via git merge or git rebase).

Analytics changes often affect the broader organization, so getting feedback is important. Typical stakeholders include the security and legal team, the growth team, and the data team.

Soliciting reviews starts with the creation of a merge request. When creating a merge request, describe the changes you're proposing and @mention any specific reviewers or approvers you'd like to include.

Merge

Once the tracking plan changes are ready, and everyone who's needed to approve has done so, you're ready to merge into main.

Once the rest of the feature team is ready to merge in Git as well, merge your branch in Amplitude Data first. This will create a new official version of your tracking plan on main and assign new versions to all new and changed events.

If your Git branch is already up to date with the merged Amplitude Data branch, you can now merge your Git branch as-is. Running ampli status --is-merged will check that your Ampli code is up to date with the merged Data branch. If the command returns an error, run ampli pull to update the generated library to the latest version.

After ampli status --is-merged is successful, you can merge the Git branch.

To learn more about developer branching workflows, visit the Amplitude Developer Center.