Skip to content

Adds some general information about considerations for upgrades #7288

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
+261 −203
Open

Adds some general information about considerations for upgrades #7288

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
23c3c18
Adds some general information about considerations for upgrades
AndyButland Aug 7, 2025
7cb8de7
Avoid use of 'we'
AndyButland Aug 7, 2025
7ea0de0
Linting
AndyButland Aug 7, 2025
3500e1d
Updates from review
AndyButland Aug 12, 2025
d63d10c
Split article into two with an introductory page
AndyButland Aug 12, 2025
8d4e68d
Shorter sentence
AndyButland Aug 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 38 additions & 1 deletion 16/umbraco-cms/fundamentals/setup/upgrading/README.md
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we refer to where this communication is made, e.g., Release Notes and Announcements on GitHub, and Release Blog Post on umbraco.com?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do have that actually - in the sentence:

Umbraco communicates about the breaking changes in release blog posts and on the documented version specific upgrade details.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we use "obselete" more than we use "legacy". Perhaps rewrite to:

They are only removed in major versions and with plenty of notice under announcements on the Umbraco repository on GitHub. When a feature is deprecated, a minor version is released with the deprecation, and the feature is deprecated for the next major release.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have rewritten this slightly - mainly to add reference to the announcements repository, which is good to call out I agree. On the wording though, I think legacy is right here when we talk about features, and it's the word we used when retiring "Nested Content" for example. Obsolete is more used for code APIs.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All good, if "legacy" is the right wording. I just noticed we use "deprecation" on this page https://umbraco.com/products/knowledge-center/versioning-and-release-cadence/

Original file line number Diff line number Diff line change
Expand Up @@ -8,19 +8,56 @@ In this article, you will find everything you need to upgrade your Umbraco CMS p

You will find instructions on how to upgrade to a new minor or major version as well as how to run upgrades unattended.

* [What is involved in an upgrade](./#what-is-involved-in-an-upgrade)
* [Before you upgrade](./#before-you-upgrade)
* [Upgrade to a new Major](./#upgrade-to-a-new-major)
* [Upgrade to a new Minor](./#upgrade-to-a-new-minor)
* [Run an unattended upgrade](./#run-an-unattended-upgrade)

## What is involved in an upgrade

When upgrading to a new version of Umbraco, there are four key aspects of the migration to be aware of.

### Database schema and content

Firstly there's the update of your Umbraco database's schema and how the content is stored. On occasion changes are necessary to support a new feature. This might be adding new tables or columns, or updating the stored data. This is something Umbraco takes care of for you. When Umbraco starts up and is running a newer version, the necessary changes will be detected and applied.

As a developer responsible for the Umbraco website, there's nothing specific you need to do here. We will communicate key migrations that will happen on major version upgrades. As if you have a large site and significant amounts of data need to be updated, the migration could take some time to complete.

Minor or patch versions may contain schema and content updates too, but they won't be extensive.

### Supported features

Secondly you should review your use of property editors to ensure that they are available on the new version. It's rare for these to be removed, but it can happen when better alternatives are available. These are only removed in major versions and with plenty of notice. They will have been indicated as legacy on earlier versions.

### Project customizations

The third aspect is determining and verifying that your own code customizations are compatible with the new version. This includes C# server-side functionality, Razor templates and JavaScript backoffice extensions.

Extensive efforts are made to avoid breaking changes that would cause issues for these types of customization other than in a major version update.

### Third-party packages

Finally you should consider the packages you are using on your project. You will need to verify that the package will work with the new version of Umbraco. Or that a compatible upgrade of the package is available or planned.

As above, we endeavour to avoid breaking changes that would prevent packages from working other than in a major version update.

### Considerations for major version upgrades

For the reasons described, projects always need to be considered case by case when upgrading to new versions.

We will communicate clearly about the breaking changes and there will be extended release candidate periods to ensure upgrades can be tested and to help package developers support new major versions.

We always try to minimize breaking changes but there will be cases when such updates are needed. How easy the upgrade will be depends on the breaking changes included in the major and whether your project(s) are impacted by them.

## Before you upgrade

The following lists a few things to be aware of before initiating an upgrade of your Umbraco CMS project.

* Sometimes, there are exceptions to general upgrade guidelines. These are listed in the [**version-specific guide**](version-specific/). Be sure to read this article before moving on.
* Ensure your setup meets the [requirements](../requirements.md) for the new versions you will be upgrading your project to.
* Things may go wrong for different reasons. Be sure to **always** keep a backup of both your site's files and the database. This way, you can always return to a version that you know works.
* Before upgrading to a new major version, check if the packages you're using are compatible with the version you're upgrading to. On the package's download page, in the **Project compatibility** area, click **View details** to check version-specific compatibility.
* Before upgrading to a new major version, check if the packages you're using are compatible with the version you're upgrading to. On the package's page on the [Umbraco Marketplace](https://marketplace.umbraco.com/), check the "Umbraco versions" field.

{% hint style="info" %}
It is necessary to run the upgrade installer on each environment of your Umbraco site. This means that you need to repeat the steps below on each of your environments in order to complete the upgrade.
Expand Down