Upgrade the Version of OSF in a Workspace

Retail Digital Commerce provides tools for upgrading your version of OSF to a newer version.

When you first create a workspace from the Retail Digital Commerce registry, the workspace has the latest version of OSF. However, the OSF version in the registry is updated regularly, so the version in your workspace may no longer be the latest. To receive new features and enhancements, it is a good idea to upgrade your workspace periodically.

To determine the version of OSF your workspace is currently running, use the version command. For example: 

yarn occ version

[cli] info: Versions:
[cli] info: - OSF CLI: 2.26.0
[cli] info: - core-retail-digital-commerce-reference-store: 2.26.0
[cli] info: - Retail Digital Commerce server: 21.3.9
[cli] info: OSF v2.26.0
[cli] info: Latest available version of OSF is v2.27.1

If your workspace does not have the latest version of OSF, you can upgrade to the latest version using the upgrade command. This command updates the version of OSF packages used throughout the workspace. Typically it is used to upgrade to a higher-numbered version, though in certain cases it can also be used to downgrade to a lower-numbered version. Note that it does not update the version of non-OSF packages.

The primary way to use the upgrade command is to update the version of OSF in a workspace to the latest version allowed by your Retail Digital Commerce server, provided that both versions have the same major version number. To do this, invoke the command without any flags: 

yarn occ upgrade

So, for example, if the current OSF version is 2.2.3 and the latest version the server supports is 2.6.7, this command updates the workspace to version 2.6.7.

If you're uncertain of the effect an upgrade command will have on your workspace, you can invoke the command with the --dryRun flag. This returns a list of the changes the command would make but does not actually make them. For example: 

yarn occ upgrade --dryRun

If the changes are what you expect, you can then run the command without the --dryRun flag.

If the current workspace version of OSF is newer than the latest version the Retail Digital Commerce server supports, or if the workspace has a different major version number from the server, the upgrade command produces a warning and exits. You can override this behavior by using one or both of these flags:

  • --acceptDowngrade – If the current workspace version of OSF is newer than the latest version the Retail Digital Commerce server supports, the workspace is downgraded to the latest version that the server supports.
  • --latest – The workspace is updated to the latest version the server supports, even if the workspace and the server have different major version numbers. Be aware that updating to a different major version may introduce breaking changes.

To upgrade to a specific version of OSF, specify the version number explicitly in the command. For example:

yarn occ upgrade 2.13.6

If the specified version number is lower than the current workspace version, include the --acceptDowngrade flag.

Special options

The following flags may be useful in certain circumstances, but you should use them with caution:
  • --no-verifyOcc – The command does not check the server version when determining what version of OSF to upgrade to.
  • --force – The command attempts to continue rather than exiting when encountering errors (version incompatibilities, inability to contact the registry or Retail Digital Commerce servers, etc.). Can be used only if a specific version of OSF is specified. For example:
    yarn occ upgrade 2.0.0 --force

If you use either of these flags, be sure you understand the implications. It is a good idea to try the command with the --dryRun flag first to see the changes it will make before running it normally.