SFRA Versions and Releases

Choosing a specific SFRA version ensures that your base cartridge and plugin cartridges work well together. In GitHub, some versions are labeled as releases, and others are labeled as pre-releases. Releases are stable; pre-releases might be unstable.

SFRA version numbers follow the semantic versioning pattern. Semantic versioning is used for all SFRA product repositories on GitHub. In semantic versioning, there are major versions, minor versions, and patch versions.

Each major version represents a version that is not backwards-compatible with previous versions. Each minor version represents new functionality and features that are backwards-compatible within the major version. Each patch version contains bug fixes or patches that are backwards-compatible within each minor version.

SFRA version numbers have the following format:


For example: v3.3.0

This version number format applies to all SFRA GitHub product repositories, including the following:

SFRA versions have matching Git tags. For example, SFRA version v3.3.0 corresponds to the Git tag v3.3.0. All SFRA product repositories are tagged separately but follow the same pattern. After cloning the SFRA product repositories, you can fetch the tags for each repository, list the tags, and check out the same version tag for each repository to ensure you are using the same version everywhere.

For each SFRA product repository, fetch all the tags before listing them or checking them out. You can fetch the tags using the following command:

After fetching the tags, you can list them using the git tag command.

You can list the tags for an SFRA repository as follows:

For example, issuing the git tag command against the plugin-applepay repository produces the following output (this output changes over time as tags are added):

You can check out a Git tag using the following command:

For example:

When you check out a tag, Git displays a message similar to the following:

Use the suggested command to create a branch from the tag. For example:

You can then work in the branch you created, knowing that it matches the specified version (in this example, v3.3.0).

You can repeat this process for all SFRA product repositories that you want to include in your project.

The SFRA base repository (storefront-reference-architecture) is continually updated regularly, and each incremental update corresponds to a new version, but only some correspond to releases.

Development occurs on the integration branch of the base repository, and code changes are merged from the integration branch onto the main branch. Once merged, these incremental changes are considered a new version (and are tagged using a corresponding Git tag). However, only some versions are fully tested against the full suite of SFRA plugin repositories and deemed stable. These fully tested, stable releases are labeled as releases in GitHub. Other versions are labeled as pre-releases. For all versions, once the base repository is tagged, all other SFRA product repositories are tagged with matching tags.

When you view the SFRA base repository in GitHub, you can click the releases tab to view releases. For example:

Here, the v3.3.0 tag is labeled as the 'Latest Release.' This label indicates that the v3.3.0 version is fully integration-tested with other product plugins and is considered stable. It further indicates that you can check out the v3.3.0 tag not only for the base storefront-reference-architecture repository, but also for other SFRA plugin repositories (for example, plugin-applepay, plugin_wishlist, plugin_ordermanagement, and so on).

If a storefront-reference-architecture tag is labeled as 'Pre-release' in GitHub, the version has not been integration-tested with other SFRA product plugins and might be unstable. A pre-release version is compatible within its major and minor versions, as is standard for semantic versioning, but it might be unstable.

Within SFRA repositories, branches can be updated and commits can be pushed without being tagged. Nothing prevents you from checking out the main branch of any SFRA repository. But unless you check out a tag, you cannot be sure if the changes in the branch are compatible with other SFRA repositories. By checking out only tags that are labeled as releases, you can be confident that you are starting with a stable code base. You can also be confident that all like-tagged SFRA plugin repositories have been integration-tested against the base repository.