Skip to content
Snippets Groups Projects
Commit 2c371ef9 authored by Jess's avatar Jess
Browse files

Issue #3136302 by Webbeh, bnjmnm, catch, xjm: Replace UPDATE.txt with links to d.o documentation 

(cherry picked from commit 7546ecb1)
parent cf3b53a6
Branches
Tags
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 46 additions and 211 deletions
core/UPDATE.txt
+ 46
− 211
View file @ 2c371ef9
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
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment