App versions

When you deploy changes to your app, Forge will create a new app version in the environment you specified (by default, this is the development environment). As you iterate on the app and deploy changes, you'll create more versions. Each app version can be major or minor, depending on the app change you introduce:

Forge handles versioning automatically, and creates major or minor versions depending on the app change you’re deploying.

Versioning

Forge creates and maintains versions on a per-environment basis. As such, when you deploy app changes to production resulting in a new major version, this version becomes available for all customer sites in production.

Likewise, if you deploy a new minor version to a major version in production, it will automatically be applied to all customer sites running that major version in production.

Forge apps created via the Developer Console or Forge CLI will initially have a version of 1.1 (major version 1, minor version 1).

Viewing installed versions

There are different ways to see what version of your app is installed on each site, in each environment:

• The forge install list command will display the major version installed on each site:

• In the Developer Console, your app's Installations page (under MONITOR) will display the major and minor version. The first segment of the version is the major version number. All sites on the same major version will also be on the same minor version:

• In the Developer Console, your app's Deployments page (under BUILD) will show who performed each deployment (Contributor), and when. It’ll also show which major version each deployment targeted within an environment:

Major version upgrades

Major version upgrades are not applied to an app installation immediately. This is because major versions involve significant changes that may require users and admins to re-consent or review the changes before continuing.

The following manifest.yml file changes are considered major version upgrades:

• Modifying scope permissions. This includes:
  • Adding a scope.
  • Swapping a scope for one not already listed.
  • Removing a scope.
• Modifying content permissions CSP options. This includes:
  • Adding a CSP option.
  • Swapping a CSP option for one not already listed.
• Modifying external permissions CSP options and URLs. This includes:
  • Adding a CSP option or URL.
  • Swapping a CSP option or URL for one not already listed.
• Adding or removing providers.
• Changing a provider client ID.
• In most cases, updating your app’s remote backends will result in a new major version. See the Remotes reference for details on which changes result in major and minor versions.

You can use the Forge CLI to complete a major upgrade with forge install --upgrade. Site admins can select upgrade from the manage apps screen to complete the app upgrade.

Minor version upgrades

Forge creates a new minor version whenever you deploy app changes that don’t result in a new major version. You can apply minor version updates to any major version, even older ones.

Unlike major versions, minor version upgrades do not require admin consent. When you deploy a new minor version, Forge automatically installs it to all sites running the same major version. This means that every site is always running the latest minor version of each app’s major version.

Backporting

In some cases, a site admin can’t or won’t upgrade from an older major version of your app. You can still backport minor version upgrades to their app. When you do, Forge will automatically apply that minor version upgrade to all sites running the same major version.

To do this, use the --major-version option:

1
2
forge deploy --major-version [version] --verbose

The --verbose option will provide you with more useful details about any deployment errors. These details include whether your attempted deployment would have resulted in a new major version.