|
1 | | -This file contains instructions for updating your WxT-based Drupal site. |
2 | | - |
3 | | -WxT has a two-pronged update process. Out of the box, it provides a great |
4 | | -deal of default configuration for your site, but once it's installed, all that |
5 | | -configuration is "owned" by your site and WxT cannot safely modify it |
6 | | -without potentially changing your site's behavior or, in a worst-case scenario, |
7 | | -causing data loss. |
8 | | - |
9 | | -As it evolves, WxT's default configuration may change. In certain limited |
10 | | -cases, WxT will attempt to safely update configuration that it depends on |
11 | | -(which will usually be locked anyway to prevent you from modifying it). |
12 | | -Otherwise, WxT will leave your configuration alone, respecting the fact |
13 | | -that your site owns it. So, to bring your site fully up-to-date with the latest |
14 | | -default configuration, you must follow the appropriate set(s) of instructions in |
15 | | -the "Configuration updates" section of this file. |
16 | | - |
17 | | -## Updating WxT |
18 | | - |
19 | | -### Summary |
20 | | -For a typical site that has a properly configured directory for exporting config |
21 | | -that is managed by your VCS, you would generally follow these steps: |
22 | | - |
23 | | -#### In your development or local environment. |
24 | | -1. Read the [release notes](https://github.com/drupalwxt/wxt/releases) |
25 | | - for the release to which you are updating, and any other releases between |
26 | | - your current version. |
27 | | - |
28 | | -1. Update your codebase, replacing `[WxT]` with the most recent |
29 | | - version of WxT. For example, `3.0.8`. |
30 | | - |
31 | | - ``` |
32 | | - composer self-update |
33 | | - composer require drupalwxt/wxt:~[WXT_VERSION] --no-update |
34 | | - composer update drupalwxt/wxt --with-all-dependencies |
35 | | - ``` |
36 | | -1. Run any database updates. |
37 | | - |
38 | | - ``` |
39 | | - drush cache:rebuild |
40 | | - drush updatedb |
41 | | - ``` |
42 | | -1. Run any WxT configuration updates. |
43 | | - |
44 | | - ``` |
45 | | - drush cache:rebuild |
46 | | - drush update:wxt |
47 | | - ``` |
48 | | -1. Export the new configuration. |
49 | | - |
50 | | - |
51 | | - ``` |
52 | | - drush config:export |
53 | | - ``` |
54 | | -1. Commit the code and configuration changes to your VCS and push them to your |
55 | | - destination environment. |
56 | | - |
57 | | -#### On your destination environment. |
58 | | - |
59 | | -1. Run any database updates. |
60 | | - |
61 | | - ``` |
62 | | - drush cache:rebuild |
63 | | - drush updatedb |
64 | | - ``` |
65 | | - |
66 | | -1. Import any configuration changes. |
67 | | - |
68 | | - ``` |
69 | | - drush cache:rebuild |
70 | | - drush config:import |
71 | | - ``` |
72 | | - |
73 | | -#### Configuration Management |
74 | | -If you are using configuration management to move your configuration between |
75 | | -development, staging, and production environments, you should export |
76 | | -configuration after #5 and deploy. |
77 | | - |
78 | | -### Composer |
79 | | -If you've installed WxT using our [Composer-based project template](https://github.com/drupalwxt/wxt-project), all you need to do is: |
80 | | - |
81 | | -* ```cd /path/to/YOUR_PROJECT``` |
82 | | -* ```composer update``` |
83 | | -* Run ```drush updatedb && drush cache:rebuild```, or visit ```update.php```, |
84 | | - to perform automatic database updates. |
85 | | -* Perform any necessary configuration updates (see below). |
86 | | - |
87 | | -### Tarball |
88 | | -**Do not use ```drush pm-update``` or ```drush up``` to update WxT!** |
89 | | -WxT includes specific, vetted, pre-tested versions of modules, and |
90 | | -occasionally patches for those modules (and Drupal core). Drush's updater |
91 | | -totally disregards all of that and may therefore break your site. |
92 | | - |
93 | | -To update WxT safely: |
94 | | - |
95 | | -1. Download the latest version of WxT from |
96 | | - https://www.drupal.org/project/wxt and extract it. |
97 | | -2. Replace your ```profiles/wxt``` directory with the one included in the |
98 | | - fresh copy of WxT. |
99 | | -3. Replace your ```core``` directory with the one included in the fresh copy |
100 | | - WxT. |
101 | | -4. Visit ```update.php``` or run ```drush updatedb``` to perform any necessary |
102 | | - database updates. |
103 | | -5. Perform any necessary configuration updates and/or migrations (see below). |
104 | | - |
105 | | -## Update instructions |
106 | | - |
107 | | -These instructions describe how to update your site to bring it in line with a |
108 | | -newer version of WxT. WxT does not make these changes automatically |
109 | | -because they may change the way your site works. |
110 | | - |
111 | | -However, as of version 3.0.2, WxT provides a Drush 9 command which *can* |
112 | | -perform updates automatically, confirming each change interactively as it goes. |
113 | | -If you intend to perform all the updates documented here, this can save quite |
114 | | -a bit of time! |
| 1 | +## Updating |
115 | 2 |
|
116 | | -That said, though, some of these updates involve complicated data migrations. |
117 | | -Due to their complexity, WxT *never* automates them -- you will need to |
118 | | -take some manual action to complete these updates, which are denoted as such |
119 | | -below. |
120 | | - |
121 | | -### Automatic configuration updates |
122 | | - |
123 | | -Ensure Drush 9 is installed, then switch into the web root of your |
124 | | -WxT installation and run: |
| 3 | +A reminder that **[composer](https://getcomposer.org/download/)** is required for the installation and updating of **[Drupal WxT](https://github.com/drupalwxt/wxt)**. |
125 | 4 |
|
| 5 | +**[Drupal WxT][wxt]** relies on Drupal’s configuration system for configuring default features and functionality. A consequence of this is, once you have installed Drupal WxT, that we cannot modify the sites configuration without having an impact on your site. Drupal WxT will, however, offer to make changes to your configuration as part of the update process. |
| 6 | + |
| 7 | +If you've installed WxT using our **[Composer-based project template][wxt-project]**, all you need to do is following the given steps below. |
| 8 | + |
| 9 | +## Update Process |
| 10 | + |
| 11 | +When pushing to production you should make sure everything has been tested in a local development environment. |
| 12 | + |
| 13 | +These are the typical steps you should following when updating Drupal WxT: |
| 14 | + |
| 15 | +a) Read the **[release notes][releases]** for the release to which you are updating along with any releases in between. |
| 16 | + |
| 17 | +b) To update your WxT codebase you would replace `[VERSION]` with the release version you wish to use. |
| 18 | + |
| 19 | +```sh |
| 20 | +composer self update |
| 21 | +composer require drupalwxt/wxt:[VERSION] |
| 22 | +composer update |
126 | 23 | ``` |
127 | | -$ drush update:wxt |
| 24 | + |
| 25 | +> **Note**: We highly recommend that you are using the v2.x.x line of Composer. |
| 26 | +
|
| 27 | +c) Run any database updates: |
| 28 | + |
| 29 | +```sh |
| 30 | +drush cache:rebuild |
| 31 | +drush updatedb |
128 | 32 | ``` |
129 | 33 |
|
| 34 | +> **Note**: You may instead go to `/admin/config/development/performance` to clear caches and `/update.php` to run database updates. |
130 | 35 |
|
131 | | -To run all available configuration updates without any prompting, use: |
| 36 | +d) Run any WxT configuration updates: |
132 | 37 |
|
| 38 | +```sh |
| 39 | +drush cache:rebuild |
| 40 | +drush update:wxt |
133 | 41 | ``` |
134 | | -$ drush update:wxt --no-interaction |
| 42 | + |
| 43 | +> **Note**: You may instead go to `/admin/config/development/performance` to clear caches and `/update.php` to run WxT updates. |
| 44 | +
|
| 45 | +## Configuration Management |
| 46 | + |
| 47 | +If you are using configuration management to move your configuration between development, staging, and production environments, you should follow the standard Drupal process. |
| 48 | + |
| 49 | +a) Export the new configuration: |
| 50 | + |
| 51 | +```sh |
| 52 | +drush cache:rebuild |
| 53 | +drush config:export |
| 54 | +``` |
| 55 | + |
| 56 | +b) Commit the code and configuration changes to your source code repository and push them to your environment. |
| 57 | + |
| 58 | +c) Import any configuration changes: |
| 59 | + |
| 60 | +```sh |
| 61 | +drush cache:rebuild |
| 62 | +drush config:import |
135 | 63 | ``` |
136 | 64 |
|
137 | | -If you'd rather do the updates manually, follow the instructions below, |
138 | | -starting from the version of WxT you currently use. For example, if you |
139 | | -are currently running 2.2.0 and are trying to update to 2.2.6, you will need to |
140 | | -follow the instructions for updating from 2.2.0 to 2.2.1, then from 2.2.1 to |
141 | | -2.2.2, in that order. |
| 65 | +<!-- Links Referenced --> |
142 | 66 |
|
143 | | -### 3.0.6 to 3.0.8 |
144 | | -There are no manual update steps for this version. |
| 67 | +[releases]: https://github.com/drupalwxt/wxt/releases |
| 68 | +[wxt]: https://github.com/drupalwxt/wxt |
| 69 | +[wxt-project]: https://github.com/drupalwxt/wxt |
0 commit comments