Package Management

Overview

After your submitted package is approved, you'll get access to a Package Management site as part of the approval process. From this location you can find a list of all of your approved packages, and can manage aspects of the how your Packages are displayed on the Official package list. This article focuses on package versions, however.

Package Versions

This list does not participate in the process of updating a package. See the How Foundry checks for Package Updates section for more information.

This section directly populates the list of released versions in the Foundry System & Modules section of the website and informs the package installation UI within Foundry which version to download. There is no limit to how many package versions you can have, and we can leverage this to allow users to backtrack and install a previous version. This also allows us to "un-release" a version if it turns out there's problems with it, rolling back to a previous version.

Deleting the latest version from this list will prevent new installations from the UI from installing, but will not prevent updates if the manifest url points to a json with a later version.

All packages submitted to the repository start with one empty version initially. You can click Add another Package Version to create a new version to fill out. 

At the far right of a version row, you can click Delete to remove the version on that row. Note: There is confirmation when deleting a version, and no way to undo this. If you delete a version accidentally, you will need to re-add and fill it out again to restore it.

If a package has no Package Versions present, it will not be available on either the official package list or in the Foundry UI.

Version Number

This is the version number of the package. This should match the version number of the linked module.json. If this increments but the linked manifest json's version field has not incremented, automatic updates will not pick up the change.

Package Manifest URL

This is the url to the module.json for this particular release. This module.json should have a download field that points at a zip of just this release. This is important as it allows a user to go back and download/install a specific version of the module from the history.

Release Notes URL (optional)

A nice-to-have url which points to a release note for this particular release. It could link to a specific heading of a larger release notes file, or to a release-specific page. It's common to include a changelog in the repository's README or to use your source control host's release feature for this.

Required Core Version

This informs the Foundry Package Installer UI which version of the module to offer based on the Core version being used. Example: A package has two versions, one with the "Required Core Version" of 0.7.4 and one with 0.6.6. A Foundry user looking for this package on a 0.6.6 version of foundry will be served the manifest url which satisfies this requirement. Should match the minimumCoreVersion field in the linked module.json. The minimum required Foundry Core version that this particular release requires to work.

Compatible Core Version

Should match the compatibleCoreVersion field in the linked module.json. The maximum Foundry Core version you are confident to say that this package works in. Note that nothing stops a user from installing the package on a version of Foundry Core that is higher than this.

Keep this up to date at all times, especially when breaking changes happen.

How Foundry installs Packages

Foundry's package installation and update process is robust enough to allow automatic update detection and installation, while also allowing users who wish to to install a specific version of a package. Foundry also allows users the freedom to install packages from any source, not just the official list. So it's important to understand exactly how Foundry's client installs packages and checks for updates.

Setting up a package to make full use of this ability requires a little legwork, but for modules with frequent updates, the rewards are peace of mind.

Installation is fairly straightforward and can be done in one of two ways.

From the UI

1. User opens the UI, finds a package to install, clicks "Install."
   UI is populated from packages submitted and accepted to https://foundryvtt.com/packages with at least one release.
2. Foundry fetches the manifest from the latest release with a matching core version as the client that was submitted to the module's foundryvtt.com/admin page and looks for a download url within it.
3. Foundry downloads the manifest's download url and checks if it is a zip file. If so, it unzips.

From a user-input manifest url

1. User opens the UI and inputs a manifest url, clicks "Install."
2. Foundry fetches the manifest json and gets the download url from it.
3. Foundry downloads the manifest's download url and checks if it is a zip file. If so, it unzips.

How Foundry checks for Package Updates

Before 0.8.2

1. User initiates the flow by either clicking on "Check Update" an individual module or the "Update All" button.
2. Foundry fetches the manifest from the url in the currently installed package's manifest json.
3. Foundry compares the version strings of the installed module's manifest against the fetched manifest.
   2.a If the user is doing this on an individual package they have to then click the "Update" button.
4. If Foundry determines that the fetched manifest json has a newer version, it then downloads that manifest's download and checks if it is a zip file. If so, it unzips.

The above process has changed as of 0.8.2 to align with the steps below.

0.8.2+ Onward

1. User initiates the flow by either clicking on "Check Update" an individual module or the "Update All" button.
2. If the Package is listed in the Package Repository:
   2.a Foundry checks to see if the manifest field has changed in the listing and points to a newer version compatible with the installed version of Foundry.
   2.b If so, Foundry prompts the User to see if they want to use the old local value, or the new Package Repository value (recommended)
   2.c If the User selects "Yes", the local manifest is overwritten with the new value from the Package Repository
3. Foundry fetches the manifest from the url in the currently installed package's manifest json.
4. Foundry compares the version strings of the installed module's manifest against the fetched manifest.
   4.a If the user is doing this on an individual package they have to then click the "Update" button.
5. If Foundry determines that the fetched manifest json has a newer version, it then downloads that manifest's download and checks if it is a zip file. If so, it unzips.
6. If Foundry determines that no new version exists, but that new Remote metadata values exist for the version, Foundry will execute an automatic update of that metadata. The Fields that get updated and from what source are according to the following table:

API  References

The following concept is utilized when Foundry checks for updates:

• Foundry uses its isNewerVersion helper function detailed here to compare manifest version strings.