“Minor” updates and “major” upgrades clarifications

Author: AugustMiller

docs/5.x/images/cli-update-info.png

@@ -1,68 +1,116 @@
 # Running Updates
 
-Craft has a smart system based on [Composer](https://getcomposer.org) that helps you keep your site and plugins up-to-date.
+Craft has a smart system based on [Composer](https://getcomposer.org) that helps you keep your site and plugins up-to-date. This page covers routine _updates_ to dependencies, which we consider a distinct process from [major-version _upgrades_](#major-versions).
 
 <!-- more -->
 
 ## Using the Control Panel
 
-When an update is available, users with the permission to update Craft will see a badge in the [control panel](./control-panel.md) next to **Utilities** in the global navigation:
+When an update is available, users with the permission to update Craft will see a badge in the [control panel](system/control-panel.md) next to <Journey path="Utilities" /> in the global navigation:
 
 ![Screenshot of control panel cropped to “Utilities” global navigation item, which contains a circular badge with the number “1” in it](./images/update-badge.png)
 
-Click **Utilities** → **Updates**. (You can also get to this view directly from the **Updates** widget that’s installed by default in the control panel dashboard.)
+Click <Journey path="Utilities, Updates" />. You can also get to this view directly from the **Updates** widget that’s installed by default in the control panel [dashboard](system/control-panel.md#dashboard).
 
 This section displays updates for Craft CMS and installed plugins, where each version has its own collapsible panel detailing relevant changes.
 
 ![Stylized screenshot of “Updates” page, which displays two plugins with newer versions with collapsible panes detailing their changes](./images/updates.png)
 
-There may be an **Update** button next to each item and an **Update All** at the top of the screen, depending on your the <config5:allowUpdates> and <config5:allowAdminChanges> settings for your current environment. You can use those to initiate updates directly from the control panel.
+You can update one dependency at a time using its **Update** button, or update everything with the **Update All** at the top of the screen. If you don’t see these options, ensure the <config5:allowUpdates> and <config5:allowAdminChanges> settings are enabled in your current environment. We generally _do not_ recommend applying updates in a non-development environment—see our [workflow](deploy.md) page for details.
 
 ::: tip
-Craft’s [changelog](repo:craftcms/cms/blob/5.x/CHANGELOG.md) will warn you of any critical changes at the top of the release notes. While there aren’t usually any warnings, it’s always a good idea to check the changelog and [any upgrade guides](#upgrade-guides) before updating.
+Craft’s [changelog](repo:craftcms/cms/blob/5.x/CHANGELOG.md) will warn you of any critical changes at the top of the release notes. While there aren’t _usually_ any warnings, it’s always a good idea to check the changelog and [any upgrade guides](#upgrade-guides) before updating.
+
+Urgent messages from changelogs (like security patches) are exposed as a banner in the control panel to all administrators.
 :::
 
-After Craft successfully installs updates, it will run any new migrations.
+After Craft successfully installs the updates, it will run any new migrations.
 
 ## Updating from the Terminal
 
 ### Craft CLI
 
 The [`update` console command](reference/cli.md#update) can be used to update Craft and plugins.
 
-To see available updates, go to your Craft project in your terminal and run this command:
+To see available updates, navigate to a Craft project directory in your terminal and run this command:
 
-```bash
+::: code
+```bash DDEV
+ddev craft update
+```
+```bash Generic
 php craft update
 ```
+:::
+
+You should see output like this:
+
+```
+Fetching available updates ... done
+You’ve got two available updates:
 
-![An example interaction with the `update` command.](./images/cli-update-info.png)
+    - craft 5.4.8 => 5.4.9
+    - commerce 5.2.1 => 5.2.2
+
+Run craft update all or craft update <handle> to perform an update.
+```
 
 To update everything all at once, run this command:
 
-```bash
+::: code
+```bash DDEV
+ddev craft update all
+```
+```bash Generic
 php craft update all
 ```
+:::
 
 To apply a specific update, replace `all` with `craft` (to update Craft itself) or a plugin’s handle:
 
-```bash
+::: code
+```bash DDEV
+ddev craft update commerce
+```
+```bash Generic
 php craft update commerce
 ```
+:::
 
-![An example interaction with the `update <handle>` command.](./images/cli-update-plugin.png)
+```
+Fetching available updates ... done
+Performing one update:
+
+    - commerce 5.2.1 => 5.2.2
+
+Create database backup? (yes|no) [yes]:
+Backing up the database ... done
+Performing update with Composer ... done
+Applying new migrations ... done
+Update complete!
+```
 
 You can pass multiple handles in at once:
 
-```bash
+::: code
+```bash DDEV
+ddev craft update commerce element-api
+```
+```bash Generic
 php craft update commerce element-api
 ```
+:::
 
 Craft will install the latest available version(s), unless you append `:<version>` to the handle:
 
-```bash
-php craft update element-api:2.7.0
+::: code
+```bash DDEV
+ddev craft update element-api:4.1.0
 ```
+```bash Generic
+php craft update element-api:4.1.0
+```
+:::
 
 After an update is performed from the CLI, Craft will apply any relevant migrations.
 
@@ -84,7 +132,7 @@ Keep in mind that manually altering constraints _can_ lead to an irreconcilable
 
 ## Workflow
 
-Every time you [deploy](./deploy.md) your project, you should run `composer install` and `craft up` to bring that environment’s database into agreement with your packages and their expected schema version.
+Every time you [deploy](./deploy.md) your project, you should run `composer install` and `craft up` to bring that environment’s dependencies and database into agreement with your packages and their expected schema version.
 
 The same applies when working with teammates! Any time you pull new code into a project, running `composer install` will guarantee you are working with the same set of packages as your collaborators. If you’re one for automation, you can even have Craft apply migrations and [project config](system/project-config.md) at the same time by adding a special hook to the `scripts` key in `composer.json`:
 
@@ -110,8 +158,14 @@ When you buy a Craft Pro or plugin license, you are entitled to use that version
 
 ## Upgrade Guides
 
-Sometimes, there are significant changes to be aware of—even in minor versions. In these (rare) cases, we publish a guide in the [Knowledge Base](kb:development), and list it here.
+Each version of the Craft documentation contains an equivalent of the [Upgrading from Craft 4](upgrade.md) page, which covers the process of upgrading from one [major version](#major-versions) to the next.
 
-The most common changes that fit this criteria are deprecations. Deprecation notices will be accompanied by instructions for updating your code to work with the new APIs. Any features that are subsequently removed in a major release will also be noted in the new version’s upgrade guide.
+Sometimes, there are significant changes to be aware of—even in minor or “point” releases. The most common changes that fit this criteria are deprecations. Deprecation notices will be accompanied by instructions for updating your code to work with the new APIs. Any features that are subsequently removed in a major release will also be noted in the new version’s upgrade guide.
 
 Deprecation warnings will affect plugin developers more frequently than regular users—but it’s still a good idea to keep your eye on the **Deprecation Warnings** utility.
+
+### Major Versions
+
+For the smoothest upgrade experience, projects must be updated to the latest available _minor_ version preceding a _major_ version upgrade. We do not support “skipping” versions, so if your site is running Craft 3, you must first update to the latest 3.x version, then perform the 3.x &rarr; 4.x upgrade, then perform the 4.x &rarr; 5.x upgrade.
+
+You should always upgrade to the latest release in a given major Craft version—for example, you can upgrade directly from 4.12.8 (or whatever the latest 4.x release is) to 5.4.9 (or whatever the latest 5.x release is).

docs/5.x/images/cli-update-plugin.png

@@ -5,15 +5,15 @@ description: Take a peek at what’s new in Craft 5.
 
 # Upgrading from Craft 4
 
-The smoothest way to upgrade to Craft 5 is to start with a [fully-updated Craft 4 project](/4.x/updating.md). We recommend approaching the upgrade in three phases: [preparation](#preparing-for-the-upgrade), a [local upgrade](#performing-the-upgrade), and [rollout](#going-live) to live environments.
+The smoothest way to upgrade to Craft 5 is to make sure your live site is already running the [latest version of Craft 4](/4.x/updating.md). We recommend approaching the upgrade in three phases: [preparation](#preparing-for-the-upgrade), a [local upgrade](#performing-the-upgrade), and [rollout](#going-live) to live environments.
 
 <!-- more -->
 
 ## Preparing for the Upgrade
 
 Let’s take a moment to audit and prepare your project.
 
-- Your **live site** must be running the [latest version](repo:craftcms/cms/releases) of Craft 4;
+- Your **live site** must be running the [latest version](repo:craftcms/cms/releases) of Craft 4 (you cannot upgrade directly from Craft 3 to Craft 5);
 - The most recent Craft 4-compatible versions of all plugins are installed, and Craft 5-compatible versions are available;
 - Your project is free of deprecation warnings after thorough testing on the latest version of Craft 4;
 - All your environments meet Craft 5’s [minimum requirements](requirements.md) (the latest version of Craft 4 will run in any environment that meets Craft 5’s requirements, so it’s safe to update PHP and your database ahead of the 5.x upgrade):