Advice in previous commit did not actually work; change recommendation to 'drush...
[project/drush_sup.git] / README.txt
1 DESCRIPTION
2 ===========
3
4 The Drush site-upgrade command automates the process of upgrading a Drupal site
5 per the instructions in UPGRADE.txt.  There are two primary benefits of using
6 Drush site-upgrade over the manual process:
7
8  1. Automation of the tedious process required to upgrade contrib modules
9     saves on time and reduces the odds of a failed upgrade due to a mis-step.
10
11  2. Advice is given on replacement modules to use in instances where a module in
12     use on the old site has no upgrade path.
13
14 The site-upgrade command can be stopped in the middle, resumed, and ran as many
15 times as needed to perform a successful upgrade.
16
17 Note that you will still need to port the CODE for your custom theme and modules,
18 if any are in use.
19
20
21 REQUIREMENTS
22 ============
23
24 * Drush-5.4 or later required.
25
26 * Currently, only Drupal-6 to Drupal-7 upgrades are supported.
27
28
29 INSTALLATION
30 ============
31
32 If you have not already done so, install Drush as described on the Drush
33 project page: http://drupal.org/project/drush
34
35 To install Drush site-upgrade, simply change to your home directory and run:
36
37   $ drush dl drush_sup
38
39 This will put the site-upgrade Drush extension in the correct place for
40 Drush to recognize it.
41
42         NOTE: It is recommended that download drush_sup from your home
43         directory in order to allow Drush to select the correct default
44         version for drush_sup. If your current working directory is inside
45         of a Drupal 6.x site, Drush will attempt to download drush_sup-6.x,
46         which does not exist and will therefore fail.  As an alternative,
47         you could specifically request the 7.x branch via:
48
49           $ drush dl drush_sup-7.x-2.x --select
50
51         You may then select the dev version or the most recent stable
52         release.
53
54
55 USAGE
56 =====
57
58  1. Read the UPGRADE.txt document in Drupal core of the version of Drupal you are
59     upgrading to, and understand the process.  Also carefully study the module
60     upgrade procedure, available at the URL specified in UPGRADE.txt.  Drush Site
61     Upgrade follows the process described in UPGRADE.txt very closely; however,
62     one very important difference is that UPGRADE.txt instructs you to upgrade
63     your Drupal site in place, whereas `drush site-upgrade` will upgrade to
64     a separate copy of your site, leaving the orginal unmodified.
65
66  2. Use `drush pm-update` to do a minor version update of your source site to the
67     most recent available version of core and contrib.  All of your code must be
68     up to date before you begin the major version upgrade.
69
70  3. Run `drush sup` once on your source site and review the upgrade readiness report.
71
72         $ cd /path/to/drupal
73         $ drush site-upgrade
74
75      - OR -
76
77         $ drush @d6 site-upgrade
78
79     The site-upgrade will examine the modules that you have installed,
80     and will report on the availability of Drupal 7 versions of the same
81     modules.  For modules which have no version available in Drupal 7,
82     Drush Site Upgrade will offer to substitute alternate projects that
83     may perform similar functions.  Sometimes there is more than one option
84     available, in which case Drush will pick the one that it thinks is best,
85     but will offer you the chance to select a different one if you wish.
86     You may see a message similar to this:
87
88        cck: The module nodereference in this project has no D7 version
89        available, but there are multiple alternative projects that may
90        be used instead. Drush picked references:node_reference, but
91        entityreference also available.  Run again with --preferred to
92        select a different preference.
93
94     If you would rather use entityreference than references, then run
95     drush site-upgrade again with the --preferred option:
96
97         $ drush @d6 site-upgrade --preferred=entityreference
98
99     If you have multiple alternative preferences to separate, include them
100     all in a comma-separated list.  Read the project page of each
101     alternative to choose the module that seems to best meet your needs.
102
103     Sometimes, there may be preliminary steps are required before beginning
104     the upgrade; if so, you will be advised of what needs to be done.
105     For example, if you are using features, you should import all of your
106     features into the database using the `drush features-import-all`
107     command.  This command is under development in the features issue queue;
108     see http://drupal.org/node/1014522#comment-5478110 for details.
109
110     You may decide at this point that you cannot upgrade your site, because
111     needed modules or themes are not ready for Drupal 7.  If you would
112     like to attempt an upgrade, procede to the next step.  Unavailable modules will
113     be skipped.  You can always re-run the upgrade again later if you wish.
114
115  4. Prepare a site alias to describe where drush should put the upgraded
116     site:
117
118         $aliases['d7upgrade'] = array(
119           'root' => '/path/to/upgradeddrupal',
120           'uri' => 'mydrupalsite.org',
121         );
122
123     Place this alias in any file where aliases may be stored.  See the
124     Drush documentation for more information.
125
126  5. Choose the amount of prompting that you would like, and run `drush
127     site-upgrade` again.  The upgrade process involves many steps, and
128     produces a lot of output.  How much prompting you would like will
129     vary depending on how confident you are about the upgrade process.
130     This can be controlled by the various prompting options:
131
132        --prompt-all
133
134        This option is best for your first run through Drush Site Upgrade.
135        It will prompt at every stage.  Drush will tell you what it is
136        going to do before it does it.  This will give you the opportunity
137        to do some investigation in another terminal; you can even opt to
138        do the operation manually, and tell Drush to continue with the upgrade.
139
140        --prompt-all --skip-optional
141
142        The --skip-optional flag is only valid in --prompt-all mode, as
143        skip optional is otherwise the default.  There are a number of steps
144        in UPGRADE.txt that are only necessary when you are doing an upgrade
145        in place.  For example, UPGRADE.txt instructs you to take the source
146        site offline before beginning the upgrade.  Since the Site Upgrade
147        command works on a copy of your site, you may leave the source site
148        online while you work if you wish.  The --skip-optional step will
149        cause Drush to skip past this step and all similar steps automatically.
150
151        [default]
152
153        If none of the prompting options are specified, then
154        Drush Site Upgrade will automatically do all of the stages that
155        considered "straightforward", and will prompt you only for stages
156        where a decision typically needs to be made.  It is recommended to
157        run through an upgrade with more prompting at least once before
158        reverting to this mode, although it is safe enough to run with just
159        the minimal prompting provided by the default mode.
160
161        --auto
162
163        In fully-automatic mode, Drush Site Upgrade will always choose the
164        first (most reasonable) option at all stages, and will prompt you
165        only in instances where there is no reasonable default.
166
167        --core-unmodified
168
169        Drush will stop and prompt you to re-apply modifications to .htaccess
170        and robots.txt, even in --auto mode, unless you also specify the
171        --core-unmodified option to skip this step.
172
173
174  6. Run the Drush site-upgrade command with your selected target alias
175     and prompting level:
176
177        $ drush @d6 site-upgrade --prompt-all @d7upgrade
178
179  7. Step through the stages of the upgrade process, making note of any
180     problems or error messages encountered along the way.  If you stop the
181     upgrade in the middle, either by selecting the [Cancel] option or
182     due to some error, you may re-run the Drush site-upgrade command again
183     to resume the upgrade.  Drush will prompt you for your desired action:
184
185      * Resume where you left off:
186
187        The last stage executed will be ran again.  If you have a failure
188        that can be resolved manually, you can just pick up the upgrade
189        from where you last left off.
190
191      * Begin again from the start, re-using the same code:
192
193        If the target site already exists, the site-upgrade command will
194        allow you to run the upgrade again, using the code at the target
195        location.  This will allow you to manage code changes required
196        during your upgrade; just compose the code you want to use at
197        the target site, perhaps via `drush dl` of specific versions, by
198        pulling from git, or by using  a Drush Make file, and run site-upgrade
199        with this option.
200
201      * Begin again from the start with fresh code
202
203        You may also start over from the beginning, once again pulling
204        down all code needed via `drush dl` automatically.
205
206      * Resume from a backup point
207
208        Drush site-upgrade automatically backs up your target site every
209        time it runs the updatedb command.  Two backups are retained: the
210        one that was taken after Drupal core was upgraded, and the one
211        that was taken after the most recent contrib module was successfully
212        upgraded.  You may resume from either of these points at any time.
213
214  8. Review the site upgrade report at the end of the upgrade process.
215     If all went well, all lines in the report will be labeled 'OK'.  If
216     there are any problems reported, repair them manually.
217
218  9. Use the content_migrate module to migrate your cck data to Drupal 7
219     format.  The site-upgrade command automatically enables content_migrate,
220     so you only need to visit the migration page and step through your data types.
221
222 Once the site-upgrade has completed, if there were no problems, then your
223 site should be nominally functional, and all of your data should be in place.
224 There will still be work left to do, though; review all of your configuration
225 settings, and insure that everything is correct. Some settings may be dropped
226 during upgrade.  Fine-tuning of your theme may also be necessary.
227
228
229 SUPPORT
230 =======
231
232 Issues with Drush site-upgrade itself should be posted in the issue queue:
233
234   http://drupal.org/project/issues/drush_sup
235
236 If you are having problems related to error messages displayed when ENABLING
237 or UPDATING a module (or UPDATING core), please direct your support request
238 to the issue queue of the particular module that is failing.
239
240
241 ISSUES WITH UPGRADE PATH
242 ========================
243
244 This section lists some issues from various issue queues on drupal.org that
245 relate to potential problems with the upgrade path from Drupal 6 to Drupal 7.
246 Check the issues themselves for updates or improved recommendations before
247 following the instructions here.
248
249 uuid module:
250
251 http://drupal.org/node/1469942:  Before upgrading, it is necessary to update to
252 the 6.x-1.x-dev release of uuid until the 6.x-1.0-beta3 release goes out.
253
254 corrupted menus:
255
256 http://drupal.org/node/991778: If menus are corrupted after an upgrade,
257 try: DELETE FROM drupal_menu_links WHERE module = 'system';
258
259 postgres:
260
261 http://drupal.org/node/1031122 and http://drupal.org/node/1575790: In step 11,
262 download and apply the patches in these two issues.
263
264
265 CREDITS
266 =======
267
268 * Based on Moshe Weitzman's original site-upgrade code originally located in Drush core.
269 * Redesigned and maintained by greg.1.anderson.