The permanent home for the documentation of what's available when listing a package is on the "Listing your package or integration" page on the website itself. If you are new to the process of listing your package, it's worth starting there as well as reading the pre-launch blog post.
Validating your listing
We hope we've made listing your package or integration a fairly straightforward process, but recognize there are a few steps involved if you want to really make the most of the presentation. For example, it's not ideal to have to wait for the scheduled synchronization to see that everything works as it should.
We've mitigated this with a feature that will help you ensure, in real-time, that you have the necessary tags and optional JSON file setup.
If you browse to the validation page you'll be able to provide the package Id and optionally the contents of the JSON file, which we'll run some validations on to make sure that it meets the requirements of listing on the Marketplace. Checks include:
- Presence of the required NuGet tag
- Retrieval of the hosted JSON file from the NuGet project URL
- Schema validation of the file
- Validation of specific elements like URLs
- Presence of a custom readme file.
With this in place you'll be able to check your prepared listing and, once validated, will be able to be confident that when the scheduled synchronization occurs it'll categorize and display your package as you expect.
You'll also be able to request an immediate synchronization of your package information following a successful validation, rather than waiting for the update to occur on the usual schedule.
Overriding NuGet information
The information we display on the website comes primarily from two sources: NuGet and the additional information provided by package owners. We've had a few cases where people had good reasons for wanting to display different information when the package is displayed on NuGet and the Umbraco marketplace.
We now allow you to provide a package title, description, readme content, and author name, specific for use on the Umbraco marketplace, so you can best describe your package to that audience.
As a straightforward example, mentioning the word Umbraco in the title or description on NuGet makes a lot of sense, but on the marketplace, everything is related to Umbraco. By populating the Title and/or Description field of the umbraco-marketplace.json file, we'll display that instead of the value retrieved from NuGet.
Similarly, by default, we will display the readme information gleaned from the listing on NuGet for a package. However, if you host a file by the name of umbraco-marketplace-readme.md in the same location as the umbraco-marketplace.json file, we will import and display that instead.
Automating contributors and packages by the same author
With the initial release we provided a means for package developers to provide an explicit listing of contributors and other packages built by the same author. This still exists, and if provided we'll continue to use that information to populate the respective areas of the listing.
However, for both of these, you can now omit or remove this information, as we have an automated means of importing this information.
- If you provide a SyncContributorsFromRepository flag in the umbraco-marketplace.json file, within the AuthorDetails element, and a GitHub source code repository is listed in the NuGet details, we'll pull in the contributors from GitHub. That way it'll keep up to date with contributors to your source code.
- You can see an example of this here, reflected in this package's listing.
- We'll load packages by the same author based on the owners of the package on NuGet, displaying all packages that have an overlapping owner with the one being viewed.
Multiple packages for different Umbraco versions
Many packages are versioned along with Umbraco - so if a new version of a package is made available with changes necessary for say Umbraco 11, they'll be released on the same NuGet package ID with their own new major version.
We've found quite a few developers though preferring to create new NuGet package IDs for new versions - so there will be a "MyPackage.10" for Umbraco 10, and "MyPackage.11" for Umbraco 11, etc.
If that matches your setup, you can just list them separately. But it's perhaps not ideal - neither for yourselves having to maintain listings for different versions nor for those looking for packages and finding what seems to be duplicated.
Instead, you can just list your latest package, and use the VersionSpecificPackageIds element of the umbraco-marketplace.json file to indicate which other packages should be used for older Umbraco versions.
We do this for example for Umbraco Forms - see example here - where we indicate that for Umbraco 8, the package Id to use is "UmbracoForms" rather than "Umbraco Forms". This will extend the version range displayed on the website. And if someone is searching for packages that support Umbraco 8, they'll see install instructions that indicate which package Id and version to use:
Remember to only list the "installable component"
Many package developers choose to break up their Umbraco package into multiple NuGet packages - for example having "MyPackage.Core" as well as "MyPackage". The latter is the one that consumers of the package will install into their Umbraco web application projects.
And it's only this one that we really want to be listed on the Marketplace - there's no real value in listing the other components and they will tend to look like duplicates. As such, please make sure to only tag the single one you expect most users to want to install.
If you've mistakenly tagged both, then if, in your next release, you remove the tag from the package components you don't want to list, they will be automatically delisted.
Listing of "sub-packages"
Sometimes a package has one or more "add-ons" - further packages that extend the original one in some way but don't really merit a full listing themselves. These could be extensions for working with uSync or Umbraco Deploy, or perhaps variations on themes from a starter kit.
They can just be listed as normal, but again they can come over as looking like duplicates in the listings. We have an option available to allow them to be presented as a collection on the main package's page, but remove them from the main category listings and search results.
To use this you just need to set the IsSubPackageOf field in the umbraco-marketplace.json file to the NuGet ID of the primary package.
—
Thanks again to all the package developers that have taken the time to list their packages, as well as to those who have provided feedback on how they have found the process and given ideas for how it can be improved. We're still welcoming suggestions on the issue tracker and look forward to seeing new packages being listed, and existing ones tweaked and augmented, using some of the features described here.
If you want to be updated on the latest Umbraco package-related news and events you can subscribe to the Umbraco Package Developer Newsletter and I’ll make sure to keep you informed.