App release notes

Merchants need to quickly understand what’s changed in our apps and why, so they can get back to running their business.

To “get out of the way” of our merchants, write notes that are functional, reliable, and usable.


Overview

App release notes should:

  • Be helpful and informative. Focus on important information that merchants need to know, without being overly technical or promotional.
  • Use straightforward and plain language. Explain what changed and what the benefit is as efficiently and clearly as possible.
  • Reflect the scale of the release—if it’s truly significant, tell people.
  • Be specific. Never use generic descriptions like “Bug fixes and improvements.” If we fixed a problem or updated something, tell merchants what we fixed or updated.
  • Be accessible to all. Merchants come from different backgrounds, locations, and levels of experience. We want everyone to understand us.
  • Avoid being clever or congratulatory. We build products that affect people’s livelihoods: even if we played a role in their success, this isn’t about us.
  • Avoid witticisms or humour; always consider the audience’s perspective first. Shopify’s brand is not humorous and jokes can be read as an obstacle to getting back to work.

Recognizably Shopify

Each product has its own personality: our Android and iOS apps are different from POS or Shop. However, they should each be recognizably Shopify, and should follow our principles and rules.

Hierarchy

  • Prioritize notes in terms of importance—most important first
  • Start with updates unless the bug fix is critical
  • Group related fixes or updates together when possible—less is more
  • Releases are capped at 500 characters on Android and 4000 on iOS—aim to keep them under 500 characters

Writing style

  • Use the active voice and the past tense (“We fixed…” or “We updated…”) to explain that action we took
  • Use complete sentences
  • Explain when changes are “based on merchant feedback” or when “we received reports of…” something that needed to be fixed
  • When there’s feature parity across platforms (iOS, Android), use the same language

Punctuation

  • Use bullet points
  • End sentences with periods
  • Use commas (,) but don’t use semicolons (;) colons (:), exclamation marks (!), ellipses (...), or question marks (?)
  • Use em-dashes (—) to help with readability while remaining conversational
  • Don’t use any text formatting, including bold and italics

Sentence patterns

There are many ways to describe an update or change. Try to choose the pattern that explains what’s changed and why it matters in the simplest way possible. When in doubt, boring is best.

A product update or new feature

Be specific about what can be achieved and where it can be achieved with the new feature:

  • {x} is now available.
  • You can now {x}.
    • You can now manage your local deliveries from the orders screen.
  • We made it {x} so that {y}.
    • We made it quicker to do common actions across Shopify. You can now use context menus on iOS 13 or later.
  • We updated {x}.
    • We updated the Support screen so it loads faster.
  • You asked for {x}, so we added {y}.
  • We heard your feedback and made {x} change based on it.

A resolved crash or bug

Be specific about what was broken and what is now fixed.

  • We fixed an issue with {x}.
    • We fixed a crash that affected unlocking the app with Face ID or Touch ID.
  • You couldn’t {x}. We fixed that.
    • Sometimes you couldn’t share, edit, or duplicate discounts. We fixed this. (Use this pattern sparingly, and not for major fixes)
  • We received reports of {x} and made {y} changes.

Standalone updates

If a release is large and affects a majority of merchants, introduce the update and then use bullet points to break down each smaller part:

The Shopify mobile app now uses {x} to do {y}.

  • Benefit 1
  • Benefit 2
  • Benefit 3

Generic updates

Releases should always be specific enough to avoid general or generic messaging.

  • We fixed an issue with archiving draft orders.

  • Various bug fixes and updates.


Notes structure

Always start releases with updates unless the bug fix is urgent.

Multiple updates

Use in-line headers to indicate what’s an update and what’s a bug fix, for example:

Update: View and fulfill local delivery orders from the smart grid or Orders page.

Bug fix: Logging out from one store and into another no longer causes the app to crash.

Single updates

If we’re announcing just one type of release (update or bug fix), use one header. For example:

Bug fix: Logging out from one store and into another no longer causes the app to crash.

Mixed updates

Use in-line headers and indentation to indicate what's a standalone update, a regular update, and a bug fix. For example:

Update: The Shopify mobile app now uses Shopify ID, so you can access multiple Shopify accounts with a single login and password.

  • Quickly switch between your Shopify stores in the mobile app.
  • Access Academy, Exchange Marketplace, Shopify Community, and our Partner Program without logging in again.

Update: When editing an order, you can now add the same product more than once.

Bug fix: Swapping from one store and into another no longer causes the app to crash


Example release notes

For everyday fixes and updates, specify what was changed in a simple way.

  • We fixed an issue with archiving draft orders.

  • Various bug fixes and updates.

For infrastructure updates, explain the merchant benefit.

  • You told us the app was hard to use on slower connections—it now runs 4x faster.

  • We put the app on a diet: it’s fast and hot, just like you.

For technical updates, be specific but keep the language simple.

  • We fixed a crash that sometimes affected iPhone 5 and 4th generation iPads.

  • We fixed a crash that occurred on some 32 bit older devices.

Avoid humour.

  • We improved the speed of the app by reducing its size.

  • According to our engineers, the glass was bigger than it needed to be; we made the glass smaller.