Issue #3136302 by Webbeh, bnjmnm, catch, xjm: Replace UPDATE.txt with links to d.o documentation
xjm
parent
0f66cce399
commit
7546ecb169
259
core/UPDATE.txt
259
core/UPDATE.txt
|
|
@ -1,242 +1,77 @@
|
|||
CONTENTS OF THIS FILE
|
||||
---------------------
|
||||
|
||||
* 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
|
||||
|
||||
|
||||
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.
|
||||
This document provides links to resources on how to update or migrate your
|
||||
Drupal site.
|
||||
|
||||
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).
|
||||
|
||||
UPDATE PROBLEMS
|
||||
----------------
|
||||
If you encounter errors during this process,
|
||||
|
||||
* 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.
|
||||
|
||||
* Consult one of the support options listed on https://www.drupal.org/support
|
||||
|
||||
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
|
||||
* Refer to 'Update Drupal core via Composer' for details on using Composer:
|
||||
https://www.drupal.org/docs/8/update/update-drupal-core-via-composer
|
||||
|
||||
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:
|
||||
UPDATING CODE MANUALLY
|
||||
----------------------
|
||||
|
||||
/PATH/TO/composer update drupal/core symfony/* --with-all-dependencies
|
||||
* Refer to 'Updating the Core Software' for details on updating manually:
|
||||
https://www.drupal.org/docs/8/update/update-core-manually
|
||||
|
||||
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.
|
||||
UPDATING DRUPAL 8 TO DRUPAL 9
|
||||
-----------------------------
|
||||
|
||||
If there is a change to default.settings.php, follow these steps:
|
||||
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
|
||||
|
||||
- Locate your settings.php file in the /sites/* directory. (Typically
|
||||
sites/default.)
|
||||
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
|
||||
|
||||
- Make a backup copy of your settings.php file, with a different file name.
|
||||
3. Navigate to /update.php to initiate the update process.
|
||||
|
||||
- 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.
|
||||
UPDATING DRUPAL 6 OR 7 TO DRUPAL 9
|
||||
----------------------------------
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
If you are unable to access update.php do the following:
|
||||
|
||||
- Open settings.php with a text editor.
|
||||
|
||||
- Find the line that says:
|
||||
$settings['update_free_access'] = FALSE;
|
||||
|
||||
- Change it into:
|
||||
$settings['update_free_access'] = TRUE;
|
||||
|
||||
- Once the update is done, $settings['update_free_access'] must be reverted
|
||||
to FALSE.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue