From 7546ecb1696fa29fa2f53eaf614c5f0daea43094 Mon Sep 17 00:00:00 2001 From: xjm <xjm@65776.no-reply.drupal.org> Date: Wed, 20 May 2020 19:52:34 -0500 Subject: [PATCH] Issue #3136302 by Webbeh, bnjmnm, catch, xjm: Replace UPDATE.txt with links to d.o documentation --- core/UPDATE.txt | 257 +++++++++--------------------------------------- 1 file changed, 46 insertions(+), 211 deletions(-) diff --git a/core/UPDATE.txt b/core/UPDATE.txt index efcb5e9dd824..354c6f4815f4 100644 --- a/core/UPDATE.txt +++ b/core/UPDATE.txt @@ -1,242 +1,77 @@ -INTRODUCTION ------------- -This document describes how to update your Drupal site between 8.x.x minor and -patch versions; for example, from 8.1.2 to 8.1.3, or from 8.3.5 to 8.4.0. - -To upgrade from a previous major version (for example, Drupal 6 or 7), the -process involves importing site configuration and content from your old site -into a new Drupal 8 site. The tools and process are currently experimental, -rather than being fully supported, so be sure to test in a development -environment. You will need to use the core Migrate Drupal UI module which -provides a user interface for the Migrate and Migrate Drupal modules included -in core. See https://www.drupal.org/upgrade/migrate for details, and -https://www.drupal.org/node/2167633 for known issues. - -First steps and definitions: - - * If you are upgrading to Drupal version x.y.z, then x is known as the major - version number, y is known as the minor version number, and z is known as - the patch version number. The download file will be named - drupal-x.y.z.tar.gz (or drupal-x.y.z.zip). Previous Drupal versions used - only x.y (MAJOR.MINOR) to designate their versions. - - * All directories mentioned in this document are relative to the directory of - your Drupal installation. - - * Make a full backup of all files, directories, and your database(s) before - starting, and save it outside your Drupal installation directory. - Instructions may be found at - https://www.drupal.org/upgrade/backing-up-the-db - - * It is wise to try an update or upgrade on a test copy of your site before - applying it to your live site. Even minor updates can cause your site's - behavior to change. - - * Each new release of Drupal has release notes, which explain the changes made - since the previous version and any special instructions needed to update or - upgrade to the new version. You can find a link to the release notes for the - version you are upgrading or updating to on the Drupal project page - (https://www.drupal.org/project/drupal). +CONTENTS OF THIS FILE +--------------------- -UPDATE PROBLEMS ----------------- -If you encounter errors during this process, + * Introduction + * Minor and patch version updates + * Is my site using Composer? + * Updating code manually + * Updating code with Composer + * Updating Drupal 8 to Drupal 9 + * Updating Drupal 6 or 7 to Drupal 9 - * Note any error messages you see. - * Restore your site to its previous state, using the file and database backups - you created before you started the update process. Do not attempt to do - further updates on a site that had update problems. +INTRODUCTION +------------ - * Consult one of the support options listed on https://www.drupal.org/support +This document provides links to resources on how to update or migrate your +Drupal site. -More in-depth information on updating and upgrading can be found at -https://www.drupal.org/upgrade MINOR AND PATCH VERSION UPDATES ------------------------------- -To update from one 8.x.x version of Drupal to any later 8.x.x version, after -following the instructions in the INTRODUCTION section at the top of this file: -1. Log in as a user with the permission "Administer software updates". +Minor and patch updates are done either manually or with Composer, depending on +how the site was installed. Refer to the sections below on updating with +Composer or updating manually for tarball/zip installations. -2. Go to Administration > Configuration > Development > Maintenance mode. - Enable the "Put site into maintenance mode" checkbox and save the - configuration. +Minor and patch versions are updates such as: + * Patch releases (e.g. 9.1.2 to 9.1.3) + * Scheduled minor releases (e.g 9.3.5 to 9.4.0) + * Beta to final releases (e.g. 9.1.0-beta2 to 9.1.0) -3. Determine if your project is managed by Composer. - On a typical Unix/Linux command line, this can be determined by running the - following command (replace /PATH/TO/composer with the appropriate location - for your system): +IS MY SITE USING COMPOSER? +-------------------------- - /PATH/TO/composer info drupal/core +Before updating, determine if your site is currently managed by Composer. - If this is successful, your project is managed by Composer. +On a typical Unix/Linux command line, this can be determined by running the +following command (replace /PATH/TO/composer with the appropriate location +for your system): - If you don't have Composer installed or access to the command line, you can - check the contents of composer.json. If "drupal/core" is present in the - "require" section of your composer.json file, then the project is managed by - Composer. + /PATH/TO/composer info drupal/core - If the project is not managed by Composer, follow the steps under "UPDATING - CODE WITHOUT COMPOSER", otherwise go to "UPDATING CODE WITH COMPOSER". UPDATING CODE WITH COMPOSER --------------------------- -1. On a typical Unix/Linux command line, run the following command from the root - directory (replace /PATH/TO/composer with the appropriate location for your - system): - - /PATH/TO/composer update - - Note, if Composer is not installed you will need to install it in order to - update Drupal. - - Note, if you want to only update drupal/core the following command will - probably work: - - /PATH/TO/composer update drupal/core symfony/* --with-all-dependencies - -2. Check the release notes for the updated version of Drupal to find out if - there is a change to default.settings.php. - - You can find the release notes for your version at - https://www.drupal.org/project/drupal. At bottom of the project page under - "Downloads" use the link for your version of Drupal to view the release - notes. If your version is not listed, use the 'View all releases' link. From - this page you can scroll down or use the filter to find your version and its - release notes. - - If there is a change to default.settings.php, follow these steps: - - - Locate your settings.php file in the /sites/* directory. (Typically - sites/default.) - - - Make a backup copy of your settings.php file, with a different file name. - - - Make a copy of the new default.settings.php file, and name the copy - settings.php (overwriting your previous settings.php file). - - - Copy the custom and site-specific entries from the backup you made into the - new settings.php file. You will definitely need the lines giving the - database information, and you will also want to copy in any other - customizations you have added. - -3. Determine if there are any modifications to files such as .htaccess or - robots.txt and re-apply them. The Drupal Scaffold composer plugin - (https://github.com/drupal-composer/drupal-scaffold) can help you with - excluding files you'd like to always preserve when updating Drupal. -4. Go to the "UPLOADING THE CODE" section + * Refer to 'Update Drupal core via Composer' for details on using Composer: + https://www.drupal.org/docs/8/update/update-drupal-core-via-composer -UPDATING CODE WITHOUT COMPOSER ------------------------------- -1. Remove the 'core' and 'vendor' directories. Also remove all of the files - in the top-level directory, except any that you added manually. - If you made modifications to files like .htaccess, composer.json, or - robots.txt you will need to re-apply them from your backup, after the new - files are in place. +UPDATING CODE MANUALLY +---------------------- - This should leave you with the modules, profiles, sites, and themes - directories. These directories should only contain code that you've used to - extend Drupal. - -2. Download the latest Drupal 8.x.x release from https://www.drupal.org/download - to a directory outside of your web root. Extract the archive and copy the - files into your Drupal directory. - - Copy all the files, but do not accidentally overwrite your modules, profiles, - sites, or themes directories. - - On a typical Unix/Linux command line, use the following commands to download - and extract: - - wget https://www.drupal.org/files/projects/drupal-x.y.z.tar.gz - tar -zxvf drupal-x.y.z.tar.gz - - This creates a new directory drupal-x.y.z/ containing all Drupal files and - directories. Copy the files into your Drupal installation directory: - - cp -R drupal-x.y.z/* drupal-x.y.z/.htaccess /path/to/your/installation - - If you do not have command line access to your server, download the archive - from https://www.drupal.org using your web browser and extract it locally. - -3. Check the release notes for the updated version of Drupal to find out if - there is a change to default.settings.php. - - You can find the release notes for your updated version at - https://www.drupal.org/project/drupal. At bottom of the project page under - "Downloads" use the link for your updated version of Drupal to view the - release notes. If your updated version is not listed, use the 'View all - releases' link. From this page you can scroll down or use the filter to find - your updated version and its release notes. - - If there is a change to default.settings.php, follow these steps: - - - Locate your settings.php file in the /sites/* directory. (Typically - sites/default.) - - - Make a backup copy of your settings.php file, with a different file name. - - - Make a copy of the new default.settings.php file, and name the copy - settings.php (overwriting your previous settings.php file). - - - Copy the custom and site-specific entries from the backup you made into the - new settings.php file. You will definitely need the lines giving the - database information, and you will also want to copy in any other - customizations you have added. - -4. Re-apply any modifications to files such as .htaccess or robots.txt. - - If you have added requirements in composer.json, it is recommended that you - re-add the requirements using Composer instead of applying the changes by - hand. For example, on a typical Unix/Linux command line, to reinstall the - Address module and its dependencies run (replace /PATH/TO/composer with the - appropriate location for your system): - - /PATH/TO/composer require drupal/address - - If you do not have command line access to your server, you will need to run - the Composer commands locally before uploading the file system to your - server. - -5. Go to the "UPLOADING THE CODE" section - -UPLOADING THE CODE ------------------- -1. If you updated the code in a different environment from where it is running - you need to upload the files to your web root including the vendor/ - directory. - -2. Go to the "UPDATING THE DATABASE" section - -UPDATING THE DATABASE ---------------------- -1. Run update.php by visiting http://www.example.com/update.php (replace - www.example.com with your domain name). This will update the core database - tables. + * Refer to 'Updating the Core Software' for details on updating manually: + https://www.drupal.org/docs/8/update/update-core-manually - If you are unable to access update.php do the following: - - Open settings.php with a text editor. +UPDATING DRUPAL 8 TO DRUPAL 9 +----------------------------- - - Find the line that says: - $settings['update_free_access'] = FALSE; + 1. Prepare the Drupal 8 site for Drupal 9: + https://www.drupal.org/docs/9/how-to-prepare-your-drupal-7-or-8-site-for-drupal-9/upgrading-a-drupal-8-site-to-drupal-9 - - Change it into: - $settings['update_free_access'] = TRUE; + 2. Update the Drupal 8 codebase to Drupal 9: + https://www.drupal.org/docs/8/upgrade/upgrading-between-drupal-8-major-versions-eg-from-drupal-8-to-drupal-9 - - Once the update is done, $settings['update_free_access'] must be reverted - to FALSE. + 3. Navigate to /update.php to initiate the update process. -2. Go to Administration > Reports > Status report. Verify that everything is - working as expected. -3. Ensure that $settings['update_free_access'] is FALSE in settings.php. +UPDATING DRUPAL 6 OR 7 TO DRUPAL 9 +---------------------------------- -4. Go to Administration > Configuration > Development > Maintenance mode. - Disable the "Put site into maintenance mode" checkbox and save the - configuration. + * Updating from a previous major version, such as Drupal 6 or 7, requires + importing the old site configuration and content into a new Drupal 9 site. + Refer to the 'Migrate Guide' for more details on this process: + https://www.drupal.org/upgrade/migrate -- GitLab