Updating your theme

After you've first published a theme on the Theme Store, you begin the iterative process of considering merchant feedback, persistently innovating your build through regular quality assurance testing, and actively integrating the updates required by Shoplazza.

As a Shoplazza Theme Partner, you're required to provide ongoing updates to your theme to remain on the Shoplazza Theme Store.

The following sections describe the theme update process and the types of updates.


Theme update process

You can submit your updates for review as ZIP files through your Partner Dashboard. Each update should have a version number, determined by the content of the update, and release notes.

Merchants are shown a notification on the Online store > Themes page letting them know that they can update their theme. The merchant can apply the update to an unpublished copy of their theme so that they can review it before publishing.

To avoid update fatigue for merchants, there should be a minimum of 4 weeks between updates

📘

Note

There will be only one theme store listing per theme, which will be the latest version. This means that all reviews will show in the same listing, regardless of the theme version they were submitted for. This also means that you can't charge a different price for different theme versions.

After your update has been successfully reviewed and published, you receive an automatic notification email.


Considerations for new versions

Consider the following, and the associated merchant impact, when creating new versions:

  • If you change an existing setting so that the merchant's value is no longer valid, then the merchant's value will be reset to the default, as specified in your new version. To create less friction for existing merchants, you should keep the same default settings when possible.

  • If you change the ID of a setting, then the setting in the current theme will be considered as removed and the new setting will be added with the default value. This provides a poor merchant experience and should be avoided.

  • If you change the type of a setting, then the merchant's current setting values may be invalidated and reset to the default value.


Versioning

Theme versions help merchants easily identify which theme they have, so that they can determine which features are available, or if there are more recent versions to update to.

When building your version string, you should use semantic versioning in the format of X.Y.Z.

ComponentDescription
XRepresents a major version that introduces or modifies features that aren't backwards compatible, such as the following:

- Modifying a settings value.
- Removing a setting, section, or block.
- Adding a global setting.

For example, you might move from 1.4.8 to 2.0.0.

When a major version is released, merchants are shown a notification on the Online store > Themes page letting them know that they can apply the update to an unpublished copy of their theme to be reviewed and published.
YRepresents a minor version that introduces or modifies features that are backwards compatible, such as the following:

- Modifying the label or default value of an existing setting.
- Adding a section or block.
- Changing the visual design, or functionality, of an existing section or block without changing their setting schema.

For example, you might move from 1.4.8 to 1.5.0.

When a minor version is released, merchants are shown a notification on the Online store > Themes page letting them know that they can apply the update to an unpublished copy of their theme to be reviewed and published.
ZRepresents a maintenance version that fixes bugs or security issues, or makes non-visual code improvements.

For example, you might move from 1.4.8 to 1.4.9.

When a maintenance version is released, merchants are shown a notification on the Online store > Themes page letting them know that they can apply the update to an unpublished copy of their theme to be reviewed and published.

The theme version can be included in the theme through theme metadata.


Release notes

For each theme version, you need to have release notes that highlight the main features of the version.

The main audience for release notes is merchants, so the language you use should reflect that. Release notes aren't intended to be a changelog, but rather a curated list of items that will impact merchants, or their buyers. As such, any user-facing changes should be included, and developer-facing changes should be excluded. You should also include only information related to the current release.

Include release notes in your theme

To include release notes with your theme, create a markdown file in the root of your theme's ZIP called release-notes.md. The file's contents should contain the following components:

ComponentDescription
DescriptionA summarized description of the most important changes in this version.
List of changesA list of changes contained in the version. Changes can fall under one of the following headings:

- Added
- Changed
- Removed
- Security
- Other fixes and improvements

Changes should be listed in bullet point under their respective heading. Each heading should be treated as an H3, so needs to be preceded by ###. For example, ### Added.

If there are specific changes that you want to bring attention to, then you can prepend the change with Important:. For example:

- Important: This is an important change.

When the release notes are rendered, these important changes will be visually highlighted.

Example:

We’ve added the ability to add payment options for your customers, removed the Instagram section, and changed how the social media section works.

### Added

- Important: Added search faceted filtering
- Added selling plans to cart notifications

### Changed

- Important: Changed default social media sharing image with the one from the Store admin. You can add a default image to be used when a featured image for the page can't be found.

### Removed

- Removed the Instagram section since the API has been deprecated with no suitable replacement. From now on you'll need to switch to using an app to display your Instagram feed.

### Security

- Fixed security issues

### Fixes and other improvements

- The collection page sidebar is now aligned with the utility bar
- Fixed the 'forgot your password' link on the customer login page

Urgent updates

An urgent update is a theme update that merchants require immediately to run their business without interruption. Typically, only updates that address an issue with the purchase flow are considered urgent. The purchase flow is the process that a customer undertakes when making a purchase, starting from the product page and continuing to checkout through the dynamic checkout button, or continuing from the cart to checkout through the checkout call-to-action or dynamic checkout buttons.

If you have an update that you deem to be important that doesn't affect the purchase flow, then you can consult the Theme Partner Manager before you submit the update.