Creating your First Package ID: PM-GS-CP
TLDR
- To create a new package, open the "Advanced" menu in package manager (the gear in the top-right corner) and click on "New Package".
- All assets in the new package will come from the package's site
- If in doubt, set the default update type to "Notify administrators when a new version is activated"
Opening the New Package Wizard
If you do not have access to any packages yet, you will see a "Create Package" button in the top-right corner of the package manager. Clicking on that button will open the new package wizard.
You can also open the new package wizard by clicking on the gear in the top-right corner to open the "Advanced" menu and then selecting "New Package".
Alternatively, you can browse to (or create) a repository that you want to create the package in and click the "New Package" toolbar button.
Selecting a Site
When selecting a site for your package, you will be limited to the sites that belong to the same account. The site selected is critical because all assets and dependencies for the new package will come from the site.
Package Details
- The Package Name is the primary way that users will identify packages. This is the public package name and it will be visible to anyone with access to the package.
- The Initial Version Number is the version number for the first version of the package. The most common value here is 1.0.0, although you may change it if you wish.
- The Initial Changelog is the changelog for the first version - which will be visible in the package details. You will be able to change this any time.
- The Description should be a description of the package that makes sense to you and that you think will make sense to people who may want to install your package. This will be visible to anyone with access to the package.
- The URL, if included, should be a link to a public webpage that includes more information about the package - including documentation, sample demos, marketing materials, and more.
- The Default Update Type will determine how the package will be updated on client sites by default. Note that this is only the default value - the final value will be determined individually on each site that installs the package. The update types are explained in more detail below.
- The User Agreement, if present, is text that will be displayed to users before they install your package. Although this may be the full text of the user agreement, we recommend placing the full user agreement on a public web page and including a link to that page here instead.
Update Types
There are three update types for packages, which determine what happens when a new version is released:
- Do not do anything when a new version is activated: As stated, will not notify administrators or attempt to auto-update the package when a new version is released. When administrators view their site packages, they will still see an icon notifying them that a new version of the package is available. This may be the best default value if your package is simply a collection of package dependencies or if you are using your package for an atypical purpose.
- Notify administrators when a new version is activated: Send an email to the site package administrator(s) when a new version is released. The site package administrators are configured per site package. It is up to the administrators to update the package manually. This is the best default value for most packages.
- Automatically apply new versions when they are activated: Attempt to automatically update to the latest version when a new version is released. If there are any issues which would prevent the installation from completing successfully, the installation will have to be completed manually. In either case - if the installation is completed or if it fails - an email will be sent to the site package administrator(s) notifying them of the status of the update. This is often the easiest option for site administrators because if everything goes well they will not have to do anything to receive the latest updates. This is also the most risky option because if the update would break their site they may not know about it until their site is already broken. If you are installing your own package across a large number of sites which you control, you should consider this for your default.