After Activation ID: PM-CP-AA

So you have activated your package - what happens now? This lesson describes what happens after a package is activated, and addresses what you should do if you realize that you made a mistake in your package.

TLDR

• Activating a package version cannot be undone and has immediate affects - including automatically updating assets on sites that have installed previous versions of the package.
• The only information you can edit for an activated package version is the changelog.
• Archiving an activated package version does not remove it from any current sites - it simply prevents it from being installed on any new sites.

Immediately after Activation

The new version will be available for users to install on their sites immediately after activation.

Additionally, within minutes of activating a new version of your package Marketpath will begin updating sites and notifying administrators of the new version based on how they configured the package on their site. This is all automatic and once this process starts there is no way to stop, alter, or speed it up.

There are three possible update actions that are configured separately for each site. The simplest option is for sites that are configured to do nothing when a new update is released. Sites may also be configured to send a notification when a new version is released - in which case they will receive an email alerting of them of the new version and prompting them to update their site. The most powerful and dangerous option both for them and for you is the option to automatically update their site when a new version of the package is released.

Sites configured for automatic update will attempt to install - and publish - the new version of your package automatically without any user input. There are still a number of checks that happen during package installation, however, and if any of those checks fail then the installation will not proceed and must be completed manually. Some examples of this might be if you have added a new required mapping, if they have edited one of the assets on their site since the last update, or if one of their assets fails validation for any other reason.

Package Installation

Before a package can be installed on a site, the system checks to make sure there is not already an installation in progress. There can only ever be one installation in progress for each package on a site, which means that a failed automatic update on a site will prevent future updates for that package on that site until the failed update is either manually completed or manually abandoned.

When a package is installed on a site, the system will attempt to automatically map as many assets as possible automatically - which it does by checking for mappings from previous installations and then looking for assets on the destination site with the same name. Then, for manually installations, the user can selects and/or modify the mappings manually. They must select a mapping for all of the required assets but may leave the optional assets blank. They can choose to ignore required mappings by explicitly changing their status but doing so is not recommended because it will almost assuredly force them to manually edit other assets later.

Once the mapping is complete, all of the remaining assets from the version are copied to the site. The assets are copied as they were when the package was activated - ignoring any later changes to the source site. Since you cannot edit a version after activation, every user who installs that version on their site will get the exact same assets and dependencies at the start of their installation.

For manual installations, users have an additional opportunity to edit the assets in their installation prior to completing it. Because of this - and because of the way mapped assets work - the results of installating the same package version on different sites will often be different. Keeping this in mind while designing your package can be helpful.

If all assets pass validation - that is, if there are no errors for any of the assets in the package - the package installation may be completed. Any trashed assets in the installation will be trashed on the site, any new assets will be created, and any old assets will be updated. If there are any old trashed or locked assets that need to be updated, then those assets will be untrashed and unlocked so that they may be updated properly.

For automatic installations (from the "Automatically aply new versions when they are activated" update type), all assets in the new version will also automatically be published if the update was successful. This may have an immediate impact on live sites and so must be treated with caution both by you as the package author and by site administrators who install your package.

What if I made a Mistake?

You may be tired of hearing this by now but it is important enough to repeat again: You cannot make any changes to an activated package version. The only thing you can edit is the changelog.

You cannot make changes for a number of reasons:

1. Consistency: Everyone who installs a specific version of your package will get the exact same thing.
2. Security: Changing the contents of an activated package version would make it easier for a malicious actor to cause widespread damage both to you and anyone who uses your package.
3. Scope: Once your package has been installed and configured on other sites it would be impractical, exceedingly difficult, and potentially unethical to alter that package on those sites without the express knowledge, consent, and oversight of those site administrators.

So this leaves 2 options, both of which could be considered separately or together:

1. Release another new version to fix your mistake. If you know you activated a version with a mistake, you should almost always do this - even if you simply want to "undo" your last version. This is particularly true since sites may have been automatically updated to the bad version. Include helpful information about the issue that was fixed or reverted in the changelog. In some cases, automatic updates to the old version may still be completed prior to automatic updates to the new version.
2. Archive the version that contains the mistake. This will prevent it from being installed on any new sites, although it will not do anything about sites that are already installing or have already installed the bad version. This will not always be necessary, although if the mistake was significant - such as inappropriate data or broken functionality - then you should definitely consider this. As an added bonus, archiving old versions makes managing and installing them easier.

Note that you also cannot edit the version number after you activate a draft version, and you also cannot re-use version numbers.

Curating Old Versions

When a user installs your package on their site, they have the option of installing any of your activated versions. This may be helpful or it may be a liability depending on the specifics of your package. To simplify package management, reduce your liability, and make it easier for users selecting a version to install, you may want to archive old versions that are no longer needed or desirable. The best practice is to keep the latest version before any major or breaking changes in case sites experience issues when updating to the newer versions.

When you archive a package version you can still access the changelog for that version in Package Manager, although users installing your package will not see the changelog for archived versions. As a result, you should consider updating your changelogs when archiving old versions so that you do not lose details or valuable information for site administrators when they view and install your package.

Old archived versions will eventually be automatically and permanently deleted by the system once they are no longer present on any sites.

Archiving

• Archiving a version or package prevents users from accessing and installing it on their site.
• Archiving does NOT change sharing settings or removing anything from sites.
• Old archived versions and packages will be automatically deleted by the system after they are no longer used on any sites.
• You can unarchive versions and packages before they are deleted, which allows users to access and install them again.

---

---