The term "Package Migrations" is just a title i made up several years ago. The idea is:

• Streamline the behavior between Nuget packages and Umbraco packages for installing data
• Allow for Umbraco data to be installed via Nuget packages

There's a short writeup about this here: #15 (comment) which I've copied (and updated) here:

• makes both nuget packages and umbraco packages work as one (i.e. you will be able to install data with nuget packages in the exact same way as if an umbraco package was installed in the back office)
• developers don't have to do any dirty hacks on startup to run custom migrations, this will all be taken care of appropriately and to avoid any startup costs
• when a package migration is detected (i.e. a new package has been installed or a package has been updated where the new version has migrations), the Umbraco installer will execute, but under a different type of runtime state with a different UI showing which packages require migrations to run, then the user clicks 'upgrade' (or whatever) and the installer will run just like normal. This way we get feedback about any errors that might be occuring.
  • It would be possible to have an option to run these silently but IMO that is not a good experience since if any errors happen then "kaboom" and the user has no idea what went wrong... so what needs to happen is that we have a silent option and if errors do occur we stop the app execution and render a nice error screen stating what went wrong (in fact we should have this option for the normal installer for patch upgrades ;) )
  • Another option that should exist is that there should be a configured 'holding page' that is displayed to any public user visiting the site if the site is in an upgrade/install/migration state and only the logged in administrator actually gets redirected to the umbraco install screen
• this would obsolete the existing "package actions" xml format that requires custom xml providers/types

There's some discussion about that here #19 so wanted to move that discussion here purely about:

• Allow data to be installed by packages, nuget and the back office
• Hopefully streamline the way that data is installed by either package format: nuget or umbraco packages
• The current "package action" format is not very friendly since it requires manually writing XML and it doesn't track what has been run and not run or dealing with upgrades whereas the current umbraco Migrations does all of this

Current work arounds that package developers currently do for Nuget based packages are:

• Run custom migrations manually and in various ways that are not fully supported by Umbraco, potentially slowing down startup and not being able to report errors visually
• Install custom dashboards that require the developer who installed the package to manually execute actions on the dashboard to install the package data - this is also then required to be done on each environment

Would love to know if there are other ideas on how to make data installation and upgrades work nicely for both package formats.

https://github.com/warrenbuckley/Umbraco-Packager-CLI

On mobile all filters by category is not visible. The wrapper could have flex-wrap: wrap or similar.
Also consider move it to top eventually using flexbox order.

Two things that we would like all good packages developers to do, post release (so perhaps an article on each):

Keep The Package Up-to-date
What are the steps that should be followed after every new Umbraco major/minor release?
Test it (obviously!), then update what Our/nuget info so people know it's been tested? Could also encourage package developers to sign up to the 'package newsletter' for advance notice of breaking changes, for when that starts happening!.

Manage Feature Requests/Issues
Nothing specific to Umbraco here as it's about managing feature requests, reported issues on an open source repository (assuming the package is open source). But if this is the first time someone has published a package of any sort it would be good to help relieve the "fear factor" of this side of things.
How do you decide which feature requests to implement, how much time are you 'expected' to put in, how to find collaborators to help with the workload

Feature request

Add Migrations API for creating Umbraco elements without it conflicting with Umbraco Cloud deploy.

Type of feature

Core functionality

Detailed description

At present, if developing a package to work with both Umbraco and Nuget and if that package needs to install some Umbraco elements such as doc types, templates, data types etc, then best approach is to use Migrations and the Umbraco API to generate those elements grammatically. Unfortunately this can cause some conflicts with Umbraco deploy.

The main issue is the APIs don't allow creating elements with fixed Keys, instead the keys are generated when the entity is created. Unfortunately this means when a migration runs, it will attempt to create these elements on different environments with differing keys and they you get deploy issues as it doesn't realize these are the same things.

I think there either needs to be a way to create elements with fixed keys, or Migrations need to be somehow deploy aware so that they can know not to create elements if the deploy process is about to create them anyway.

uGardian v8 package listed in v7! it should display only one.

Package idea

• I am looking for feedback on a package I want to make
• I have an idea and am looking for help to make it

Description

I think there should be an image uploader. TEST!

There is a pending PR: umbraco/OurUmbraco#552

This issue is for suggestions and discussions about documentation for package that are not covered by https://github.com/umbraco/Umbraco.Packages/projects/1

Ideas for additional articles:

• Internationalization - ensuring your package can be easily translated
• Security - data validation, secure api controllers
• Privacy - ensure data privacy is considered. Logging to audit table, etc.

Knowledge for people new to Umbraco - high level overview of packages and what they do or are used for. Can expand upon the info already there: https://our.umbraco.com/documentation/Extending/Packages/

Package idea

• I am looking for feedback on a package I want to make
• I have an idea and am looking for help to make it

Description

When searching for e.g. "commerce" here https://our.umbraco.com/packages/ it filter the results as you type.

and also when hitting enter key, which redirect to this page:
https://our.umbraco.com/search?q=commerce&cat=project

When using browser back button it still shows the previous entered search term, but the results are no longer filtered.

Maybe store the search term in localStorage so when going back it fetch the filtered result.

The point of this would be to try to list some of the very common backoffice components, services, etc that package developers use in their packages.

We can then pass the list onto the Umbraco Core team and also publish it in the documentation. Whatever was on that list would be things you can consider "safe to use" - that means you can't expect it to never ever change, but if it does we would notify about it in good time so package devs would have a chance to adjust!

This is still in an idea state, but would surely help both the Umbraco Core team and package developers know what is safe and what isn't!

Any input or ideas are welcome!

As a package developer it's currently not possible to rename a package after it's been created.

Note: after a rename, there should be an automatic redirect from the old to the new URL.

An up to date version of https://our.umbraco.com/documentation/Extending/Packages/package-actions

As far as I can see there are only 2 now?
https://github.com/umbraco/Umbraco-CMS/blob/v8/dev/src/Umbraco.Core/PackageActions/AllowDoctype.cs
https://github.com/umbraco/Umbraco-CMS/blob/v8/dev/src/Umbraco.Core/PackageActions/PublishRootDocument.cs

The package format for Umbraco packages should be nuget packages (.nupkg). This file type is just a zip which contains all of the metadata we need.

How do we do this?

• Keep compatibility with current zip package format, but don't create packages in this format in the back office
• The new package format will still include the standard package.manifest file, except this will not contain any file references or metadata that is already included in the nuget file format
• File references are just based on what is in the zip in the /content folder, just like a nuget package works

The change isn't very dramatic but this means that:

• We would have the same package format for both the back office and nuget/visual studio
• The nuget package format is much nicer to work with
• If/When we have Package Migrations in place, it means we have a single package format that can be installed either in the back office or via visual studio and the umbraco data installation procedures will be identical thus bridging the gap between nuget and umbraco packages

This does not mean that by installing a package in the back office that it will magically pull in all dependencies ... that is another beast of a job and outside the scope of this topic.

Feature request

Now that people can see their 'draft' packages on Our, we should allow people to delete them.

Type of feature

Our feature

Detailed description

Since the change that enabled draft packages to be visible to the package owners to Our went live, I know at least one package developer who has a really old draft package now appearing in their list, and they want to delete it!

Once a package has been put live it makes sense that you can't then delete it (you would 'retire' it instead). However if a package has never been put live, I suggest there is no reason why we shouldn't allow package developers to delete it.

On the project overview page (https://github.com/umbraco/OurUmbraco/blob/master/OurUmbraco.Site/Views/Partials/Projects/ListProjects.cshtml) we show the download count like this (simplified):

var result = search.SearchResults.Skip((page - 1) * pageSize).Take(pageSize);

@foreach (var childPage in result)
{
    @GetField(childPage.Fields, "downloads", "0")<span><i class="icon-Download-alt"></i></span>
}

So it is the downloads field from the projectIndex.

On the member view page (https://github.com/umbraco/OurUmbraco/blob/master/OurUmbraco.Site/Views/Partials/Projects/MyProjects.cshtml) we get it like this:

@helper RenderProject(IListingItem project)
{
    @project.Downloads<span><i class="icon-Download-alt"></i></span>
}

Where project gets its downloads from here: https://github.com/umbraco/OurUmbraco/blob/master/OurUmbraco/MarketPlace/NodeListing/NodeListingProvider.cs#L88-L106 where it ends up with a db call.

To allow the full download count on member pages we will need to get them from the index instead.

Command-Line tool to create Umbraco Zip based packages, (work as an addition/alternative to the MsBuild / AppVayor methods?)

Much like the NuGet Pack command, which tasks a nuspec file and generates a NuGet Package, I have the start of something similar which could us a package.xml file - and generate a Umbraco .zip file.

eg.

UmbPack myPackage.zip -version 1.2.0 

Would generate version 1.2.0 of the package based on the file.

most of it would be as now, maybe with wildcard/glub support in the package file - Nuget Reference

e.g.

 <file path="../MyPackage/Bin/Release/myPackage.*.dll" orgPath="~/bin" />
 <file path="../MyPackage/App_Plugins/MyPackage/*" orgPath="~/App_Plugins/MyPackage" />

Highlight pros and cons of both package formats

When creating a package if you click one of the tabs before saving the initial package then you see an error.

The URL is https://our.umbraco.com/member/profile/packages/details?projectId=

The downloads on Our are from the package repository only, doesn't include Nuget package downloads:

However as you see on the top there, we know the Nuget alias of the package, and based on the alias you can call this API:
https://api-v2v3search-0.nuget.org/query?q=packageid:Our.Umbraco.SuperValueConverters

Which will give the total amount of downloads as well. Would be cool to add the numbers together 🙂

In the specific case of SuperValueConverters it would bump the downloads up from around 200 to around 1400, quite a significant difference!

Creating packages that add/alter Umbraco Items via Nuget is currently quite difficult and requires quite a lot of knowledge of Umbraco Migrations / Post Migrations.

Either as an addition to the core or as a package we should look at extending Migrations beyond Database modifications and work out how to perform Umbtraco actions.

Maybe create fluent Api for Umbraco objects? - I think @Shazwazza might have been looking into this at some point?

example

    Create.ContentType("myContentType")
             .Property("PageTitle", "Umbraco.TextBox")
             .Property("PageBody", "Umbraco.RTE", required: true);

Migrations are used a bit in this documentation article: https://our.umbraco.com/documentation/Extending/Database/

This article could contain the following:

• Quick description of what a migration is
• Package specific considerations (multi environments? What if you create content in a migration and they then uSync it over AND run the migration on the next env?)
• When to use a migration over fx. package action?
• Something else?

"The Starter Kit" is the current HQ-supported package that is installed by default if you're not customising your install. So one assumes it works in the latest version! Much like many packages the version info is out of date:

https://our.umbraco.com/packages/starter-kits/the-starter-kit/

I don't know who maintains this project now, but could it become the responsibility of the Packages Team? The team would then be responsible for testing it with new releases, updating its info online etc?

There is also an open PR - umbraco/The-Starter-Kit#65, Would be good to see that accepted and a new version released.

This is not me proposing the team build a new starter kit. This is about taking over the management of current package. However perhaps this would make the implementation of a new kit easier to achieve, at a future point?

I know it was completely my fault, but recently I copied the nuget package install command from a package page on Our, and pasted into VS package manager console. Hey presto I accidentally upgraded my Umbraco instance from v7 to v8 as the latest version of that package had a dependency on v8. Thank goodness for source control...

Is there anything that can be done to stop idiots like me from doing this? Anything in the nuget tools that could prompt the user to confirm before it would upgrade Umbraco?

As a simple step... what about adding a small reminder just under the Install-Package command?

I think a note like: "NB the default nuget version may not be compatible with your version of Umbraco" would have stopped me from making this mistake.

Worth doing a PR to add that reminder note, or is it just me?!

Step by step guide and explanations of what the fields do and mean similar to https://our.umbraco.com/documentation/Extending/Packages/Creating-a-Package/

I realize this is extremely subjective, but I'm sure there are a lot of UI elements that are reused a ton in packages, we should aim to document the most common ones. If we do the first few, others may pitch in with the ones they feel are important 🙂

It would be good to have dedicated documentation talking about making your packages Cloud/Deploy compatible. (Inspired by this tweet: https://twitter.com/greystate/status/1191696149310296065)

Here is an example from Articulate - https://github.com/Shazwazza/Articulate/blob/master/src/Articulate/Packaging/ArticulateInstallPackageAction.cs

There are probably lots of others out there 🙂

While doing some reading up on language files I got thinking if it might be possible to list which languages a package is setup to support out of the box. I guess this would just be a list of the lang files the package includes?

See details on lang files here:
https://our.umbraco.com/documentation/Extending/Language-Files/Language-Files-For-Packages/

Quick and dirty way is to just have check boxes added to the back office. Better way is to scan the package zip for any lang files and use those. That scan would have do be done for every upload to allow for updates/new releases.

Then on the package page we can render out a list of known supported languages. As a bonus we could then add something like "Not seeing your language listed here? Help translate it!" which could link to the Github page (assuming we have one) for the package or a page that explains how to create a new translation.

Feature request

If you want to update the versions that your current file supports you have to re-upload the same file and then set the versions as required during that process (oh and then archive the previous one and set this new one as 'current'). Could we add the ability to edit the information that you set for a file without having to upload a new one?

Type of feature

Our feature

Detailed description

When uploading a new file, you are asked to complete:

Could we allow users to edit this information for existing files?

Perhaps not the 'filetype' or supported .net runtime questions. If either of those were changing a new file would need to be uploaded I believe.

I hope this would mean that we would end up with more reliable information from the package maintainers themselves about what versions their packages have been tested on.

If the user is logged in, show the "Report compatibility" link. No need to make them click to download the file (and then reload the page) in order to do this.

Request for collaborators

What help am I looking for

Following on from reading #49 about how the popular packages are weighted, I wasn't aware that "Works on Umbraco Cloud" was a factor. So I'd like to tick that box for a few of my v7 packages, (if that's still applicable?)

According to the documentation, currently the only way is to reach out to Umbraco Cloud support via portal chat.

That feels a little disjointed - but then I don't know what the internal workflows are within Umbraco HQ. I feel happier requesting via the Packages Team.

Package info

The following packages have ValueConnectors in the Umbraco.Deploy.Contrib library, (for Deploy v2 at least), and work on Umbraco Cloud v7 projects. (In fact, they were specifically developed on Umbraco Cloud projects. 🎉)

Name: Nested Content
Link to repo: https://our.umbraco.com/packages/backoffice-extensions/nested-content/

Name: Doc Type Grid Editor
Link to repo: https://our.umbraco.com/packages/backoffice-extensions/doc-type-grid-editor/

Name: Stacked Content
Link to repo: https://our.umbraco.com/packages/backoffice-extensions/stacked-content/

Name: Content List
Link to repo: https://our.umbraco.com/packages/backoffice-extensions/content-list/

Name: Property List
Link to repo: https://our.umbraco.com/packages/backoffice-extensions/property-list/

This is less of a request and more of a query (so I apologise for breaking the template) ...

Currently the default view for packages is to view them ordered by popularity. But how is popularity calculated? I can see a few metrics that can be used, such as download count and "hearts", and presume there might be some weighting down to time period (ie. more recent downloads count more) but can't see any discernible logic in why certain packages appear first? For instance, Contour appears right at the top of the results, yet this is a package for Umbraco 6 that has been obsolete for years... It would be good to have transparency on this.

Secondly, is popularity the best way of presenting packages to people who might be new to Umbraco whilst also catering to veterans? Whilst it seems like an obvious measure of how "good" a package is, is it likely to create a feedback loop where the packages shown first are downloaded the most and then in turn become more popular? Does this limit visibility to packages that might be very useful but are more niche or just can't surface because of this loop?

I wonder whether a more curated approach might be better? Obviously this would be more subjective, but as we have a package team then could they not be trusted to "feature" packages, perhaps on rotation? Maybe adding a review or overview of the package? Obviously, there could be conflicts of interest (Hi Kevin!) but I'm sure that could be worked around.

I guess it would be interesting to discuss this since the packages page is often a first-impression of Umbraco. Is it the best it can be?

For my redirects package, I've specifically set the minimum required version to 8.1, but older Umbraco versions are still shown in the Package Compatibility section to the right.

Proposal: don't show Umbraco versions below the minimum required version.

I think it's still fine to show newer versions than what I have marked as supported. For instance, the newest version I have marked as supported is currently 8.5, but I'd imagine it works without any changes in 8.6 once out. But on the other hand, it probably won't work when jumping to the next major.

Request for collaborators

Umbraco Health Check that scans the Umbraco installation of templates that exist on disk but is not in the Umbraco back office.

Running the Health Check would notify the user of missing templates.

Running the health check would add the templates to Umbraco in the right place (so the child of another template, as required)

Package info

Name: Missing Templates Health Check
Link to repo: https://github.com/KevinJump/uSync8/tree/v8/8.2/uSync.TemplateTracker

What help am I looking for

The Template Tracker code in the repo doesn't quite work, (and the file watcher stuff is potentially dangerous) - but it could make a good health check package.

We think this might be good for someone who might want to get into package development.

I would be happy to help if someone wants to take this on as package - helping with code, package generation and all that nuget stuff.

When creating a package node on Our we should have some way for a user to flag their package as Cloud compatible.

This should then be available for the package team to test on Cloud and it could then get the "Works on Cloud" flag.

Related to #50

This is a fundamental thing missing in packages is the ability to package up media items. I'm unsure why this has never been included and don't think it would be too hard to fix up in core. If we can pacakge Content, we can package media.

Many package devs (including myself and the starter kit) have to hack a lot of things to get media items installed currently.

When you first create a package you get -1 likes under My Packages.

We need a documentation article on how to store configuration for a package. Whether it is adding config in web.config, adding to the database as described in umbraco/Umbraco-CMS#3911 or something else?

Would love to hear input on what the "best ways" are? And in which situations you would use which method.

It may be a topic that requires a bit of discussion, but I'm currently in a scenario where I have a NuGet package that isn't yet available as an Umbraco package. But I still wish to create it on Our - eg. so that users can discover said package via Our.

Given that I was able to publish my package, users would then be able to see that my package is only available on Our.

(yes, I know - I should release it as an Umbraco package as well)

Are package developers giving due consideration to the license that they are choosing for their package? Not suggesting we should be advising on what they choose (of course), but can we encourage them to think about it, rather than just assuming the default MIT license is most appropriate for them?

Interesting to see that Lee Kelleher has moved away from MIT for his new v8 package. He explains why too: https://github.com/leekelleher/umbraco-contentment

The current guidance in docs, https://our.umbraco.com/documentation/Extending/Packages/Creating-a-Package/, says "Will be set to MIT by default. If you are planning on selling your package you can change the license here". Is it a straight-forward free v commercial decision? I don't believe it is.

Perhaps some extra guidance about making sure they understand/have thought about the licensing implications and to consider alternatives (https://opensource.org/licenses) would be a good start?

The license info is asked for in the back office when creating the package and on Our when describing the package. Both UIs do allow for a short description under the label or input.

Something to discuss on next package team call?

When creating a new package, if you don't set it to be live it will get created as a node in the backoffice. However you will not be able to find it, and it won't be shown on the member profile overview.

May need to split this into more dependent on what we believe is best, but an initial list of ideas is this:

• Storing data using migrations
• Common backoffice UI components to use
• Utilizing Angular services / resources
• Using infinite editing - umbraco/UmbracoDocs#2045
• Storing configuration - umbraco/Umbraco-CMS#3911

Will let someone with more knowledge fill in what should be included here 🙂

Step by step guide on making a NuGet package out of your package. Should be similar to https://our.umbraco.com/documentation/Extending/Packages/Creating-a-Package/ but highlight some of the changes when it comes to NuGet.