v14.2.0 - The Possimpible

This is a major minor release of uSync for Umbraco v14. it contains a number of changes/improvements and feature refinements.

n.b. - we are skipping right to v14.2 because uSync now requires Umbraco v14.2. So we are (for know alignling the versions).

What's new.

• Less agressive notifications
• Improved packaging
• better migration handling .

Code tidy.
Firstly there are loads of small tweaks and changes, as we use v14 more we are finidng the best way to do certain things, so code updates and migrates to these newer 'best practices' making it all a bit more stable and hopefully usefull - the big highlights for these changes are below:

Less agressive delayed notifications.

During testing between versions we have noticed that when all the notifications are delayed and handled together a single content failure can cause none on the content items to appear on an import - if we split it all back into invidiual imports and notifications then the content that works will show up.

Umbraco v14 is a lot less forgiving of property data than Umbraco v13 which means if you have a single property with invalid data you can't import or see the content page inside umbraco. This wouldn't be a real problem as long as you never corrupt your property data. which again won't be a problem if you don't migrate and certainly will be less of a problem if you don't use the v13 Umbraco StarterKit package as a test source!

the Umbraco v13 package imports content where the property values are setup using grid JSON values inside BlockGrid properties . as an example of v13 vs v14 - this is OK on a v13 site the property doesn't load the data, but you can see the page, and you can fix that single property by updating it and editing it.

In umbraco v14 the invalid property data means the import fails, and if the page is already imported and you break the property data the actual content page will not load at all, and you would need to delete it and recreate the whole page. (we had an issue in the Umbraco Core for this type of failure, it has however being closed for now :( umbraco/Umbraco-CMS#16165 )

Improved packaing.

Its still a big learning curve how to package up things for Umbraco v14, and because uSync is actually then used inside other packages (uSync.Complete) we need to package it up in such a way that you can install it 'normally' via nuget and for development you can also install the npm client package so you can access and re-use all the components and dialogs.

with a lot of hints and help from @mattbrailsford (see https://dev.to/mattbrailsford/deploying-typescript-type-definitions-for-umbraco-v14-packages-5eg4) we know have a deployable npm package which we have been using in the contining development of uSync.Complete.

We have also followed @skttl's example and put the packagemanifest into c# code. ( https://dev.to/skttl/server-side-registering-of-package-manifest-in-umbraco-14-49go ) - the big advantage here is versioning, the version number can now be dynamically pulled from the site assemblies, so when we update the version it all happens automagically, and it doesn't change any files in the repo, so there are less random check ins. (you can see our manifestreader implimentation here : https://github.com/KevinJump/uSync/blob/v14/dev/uSync.Backoffice.Management.Client/uSyncManifestReader.cs)

Better migration handling.

uSync v14 does light touch migration when you give it v13 files, it detects this and will handle some changes from old data types into the new ones. for this version we've fixed an issue with Umbraco.Tags migrations, and we are looking again at others.

Cleaner UI.

We've added some nicer UI around progress, and errors, and details of what is going on, these don't change functionality but do make it all a bit easier to use.

v13 fixes,

• All the fixes in v13.2.4 / 2.5 and 2.6 are incorprated into this release.

---

Getting uSync

The normal way. is via nuget.

dotnet new add package uSync --version 14.2

v13.2.5 - LuCID/templates.

This is a patch release of uSync for Umbraco v13, it contains some fixes to reported issues.

Fixes

• 🐛 Fix #663 - Some Languages clash when they share an LCID
• ⭐ Allow for "clean" roots so items can deleted from the root of media/content on publish
• 🐛 #656 - Template deletes can sometimes happen out of order and cause templates to be recreated and change id,

Full Changelog: v13.2.4...v13.2.5

v13.2.4 - Patches and 🕸️🪝icon fixes

This is a patch release for uSync for Umbraco v13, it contains patches and updates for known issues.

What's Changed

• Fix #648 - Blueprint templates are not imported if the handler is disabled in the default set but enabled in another set.
• Fix #653 - Check for null 'allowedContentTypes' by @KevinJump in #654
• Fix #649 - Member composition not added to Member type on synching
• Solution re-org (makes it easier to work on multiple versions of the package)
• Fix the webhooks icon on the uSync dashboard.

Full Changelog: v13.2.3...v13.2.4

v14 - Insert AI generated image of a number 14 here.

This is a Major release of uSync for Umbraco v14 and the new Umbraco Backoffice.

Warning

Things have changed! Read all the release notes before running that add package command!,

The latest v14 release of uSync works on Umbraco v14 only. v14 of Umbraco is a complete replacement of the backoffice user interface, alongside significant changes to the API that Umbraco and packages use to communicate between the user interface and the server.

This release comes with a number of known issues with Umbraco v14, and you should check these, alongside our known issues, before you fully commit to using Umbraco v14 and/or uSync v14 on a live production site.

What's New

• New Backoffice UI.
• New Management API
• New shared npm library for other uSync packages

Known Issues

• Check Umbraco's list of v14 issues before you start.
• uSync v14 issues
• uSync.History is not yet part of this package
• See our status page for the status of all the uSync packages.

Installing

uSync can be installed as part of a calorie-controlled diet. and via NuGet for your umbraco projects.

dotnet add package uSync --version 14.0.0

Umbraco v14 Support Lifetime

It is worth noting that Umbraco v14 is a Short-Term Support (STS) release and has a limited support lifetime. Bug fix level support ends in November 2024 and the release is End of Life (EOL) March 2025. v13 of Umbraco has Long Term Support (LTS) until Dec 2025 (security updates until Dec 2026) and we would still consider v13 the sensible choice for any large-scale production-ready site development at this time.

Migrating to Umbraco v14 using uSync

Where possible, we have attempted to make it as seamless as we can to use uSync v13 files on a new uSync v14 site. However, with the number of changes to the Backoffice, alongside several property editors being removed from v14, we strongly recommend that you only migrate sites to Umbraco 14 from Umbraco v13 if you are not using any obsoleted property editors (datatypes) and you are happy with the functionality of your site and the Backoffice on Umbraco v13.

Migrating while you are using obsolete property editors might result in data and content loss, and you can’t then easily know if the issue with your migrated site is related to the new v14 Backoffice / APIs or the property editor changes you will have made.

Converting uSync/v9 to uSync/v14

For uSync v14 we have changed the default folder that uSync files are stored in from the existing uSync/v9 folder to uSync/v14. This reflects the fact that there are some changes between the uSync files on v14 and it is better to have a new clean folder for your setup then continue with the existing v9 files.

Legacy Conversion

If your site contains a uSync/v9 folder uSync will detect this and display a ‘legacy’ tab in the uSync dashboard.

This legacy tab will provide you with some information about the v9 folder and any removed property editors that it finds. It will also give you the opportunity to either ignore the legacy folder or copy it to the uSync/v14 folder where you can use it to seed your new site.

We strongly recommend that this is only performed on a development copy of your site where you have full database backups and are willing to reset the site should the migration not go smoothly.

After copying the v9 folder to uSync/v14, you can import your settings to your new v14 site. If this is successful, you should perform a clean export to get the new uSync/v14 files in the latest format for the site.

Happy uSyncing...

v13.2.3 - Patching up relations

This is a minor patch release for uSync v13 for Umbraco v13 it contains minor fixes to known issues.

What's Changed

• 🐛 Fixed #683 - relations not exporting. by @KevinJump in #639
• 🐛 Fixed #635 - duplicates when same item has multiple delete records.

Full Changelog: v13.2.2...v13.2.3

v13.2.2 - Duplicate handling fix

This is a minor release of uSync for Umbraco v13 it contains a fix to stop the false reporting of duplicates when the usync folder contains renamed elements /

Fixes

#634 & #635 - Duplicate items reported, when there are none

when something is renamed usync saves a 'empty' file over the existing item so that duplicate files don't hang around on deployments. an error creeped in v13.2.0 that didn't take full account of this and sometimes reported the renames as duplicates.

this is now fixed with this patch release.

dotnet add package uSync --version 13.2.2

v13.2.1 - Roots updates

This is a patch release of uSync for Umbraco v13, it contains some small fixes for people using roots,

What's Changed

• Fix for #623 Files are created in "default" export folder when they are the same as in the root folder
• Fix for #622 Apply button doesn't work for changes constructed from merged items.
• Fix for false positive duplicates when using clean function.

Full Changelog: v13.2.0...v13.2.1

dotnet add package uSync --version 13.2.1

v14.0.0-rc1 - release canidate-canidate beta.

This is the pre-release version of uSync v14 for Umbraco v14-rc1. It conains the working of uSync for Umbraco v14 with the new backoffice UI.

Release Notes.

The core functionality of uSync is present in this release so you can sync between sites, and key your site version controlled while working on Umbraco v14 - there are however there are several notes and cavieates to working with this release and Umbraco 14-rc1 - you should familiarize yourself with them to set expectations.

Known issues.

Umbraco Issues

There are a number of Umbraco issues that we have logged during the testing of this uSync release they affect certain types of property editors and settings within them that can cause pages or bits of your site to become un-editable, you should be aware of this issues:

• umbraco/Umbraco-CMS#16080 (Checkbox and Dropdowns don't work)
• umbraco/Umbraco-CMS#16081 (Dropdown lists cannot be set to multi-select)
• umbraco/Umbraco-CMS#16083 (Setting a Image upload folder on a Rich Text editor causes pages to not save/load)
• umbraco/Umbraco-CMS#16084 (Tags settings of CSV or Json cause pages to not save/load).

Warning

There are a couple of bugs, which mean for certain types and settings you will see errors or blank pages inside umbraco, these are not uSync issues

"Migrating" from older version.

At the moment there is no legacy to new property editor migration inside uSync, (you can however use uSync.Migrations). So migrating a site that has now discontinued property editors on (Grid, Nested Content) will not work.

It is our intention to provide a smoother migration within uSync as we approach release. but for now uSync.Migrations will provide you with the ability to migrate to BlockGrid and BlockList on a v13 site.

Note

Post RC1 - some inline migration tools for legacy to supported types will be included in uSync

DataType Migration

Internally inside Umbraco the storage and settings for a large number of the existing datatypes has changed, as such the settings stored inside any uSync files will need updating.

For known changes and types we have build this into the release! -

• Importing files from Umbraco v13 with known types will result in uSync automagically converting those datatype config values to the new format on import
• After import and when you are happy things are as expected you should perform a full export to write these new configurations out to disk

Note

RC1 - uSync will dynamically conver datatype configuration for know "supported" types from v13 to v14 formats on import

Breaking Changes

• Moving from v9-13 the default uSync folder has been renamed from uSync/v9 to uSync/v14
• The format of the configuration for datatypes has changed, migration of known types is built into to v14 (see datatype migrations) - but again custom code, might need adjusting
• There are changes to the ISyncHandler, ISyncMapper and IConfigurationSerializer interfaces any custom code might/will need updating.

Warning

** Custom code will need to be examined, updated and you might need to copy things to a new folder**

Summary

So with that all that said and absorbed, you can download and enjoy uSync as part of your brave new Umbraco world experiences.

dotnet add package uSync --prerelease

Full Changelog: v13.2.0...v14.0.0-rc1

v13.2.0 - Hook🪝and Patch 🩹 release.

This is a minor release of uSync for Umbraco v13. it contains some fixes (mainly around how deletes appear in reports and are treated by Roots and export rules), and the ability to sync webhooks between sites.

What's Fixed

• 🐛 Fix #224 - Observe root folder value in root folder array by @KevinJump in #606
• 🐛 Fix #609 Default language importing. by @KevinJump in #614
• 🐛 Use folders provided in options over config by @ljfio in #610
• 🐛 Fix #607 - datatypes don't delete on final pass. by @KevinJump in #615
• 🐛 fix #605 - check if delete file should be written to disk, by serializing item one last time. by @KevinJump in #616
• 🐛 Fix - delete entries show up twice in report and actions. by @KevinJump in #617
• 🐛 #612 -XCData Null checks by @KevinJump in #618
• 🐛 * Fix for #619. and #620 how roots reports and treats deleted items up the tree by @KevinJump in #621

What's New

• ⭐ Add serializers and handlers for webhooks. by @KevinJump in #613
• ⭐ Ability to set the history folder's location via config by @henryjump in d0f06eb

New Contributors

• @ljfio made their first contribution in #610

Full Changelog: v13.1.3...v13.2.0

v13.1.3 - Linux path patch

This is a minor patch to uSync to address an issue with uSync.Roots and paths on Linux,
You will only need to patch if you are running Umbraco on Linux

What's new

• Fix for #604 - Abs Path correction when finding path on Linux

Installing

dotnet add package uSync --version 13.1.3