The current content of the UPGRADE.txt for D6.x is very much confusing a lot of users, concerning which steps are mandatory to take for the (much more frequent) minor releases.
Especially the part on deactivating contributed and optional modules is actually telling the user to do so.
From some discussions i learned, that this step is not necessary apart from other things.
Bust mainly this step is very time-consuming and error-prone and a lot of users have nightmares facing the next minor upgrade, cause they stick to the basic instruction document!
I browsed all documentations besides the UPGRADE.txt, but they just produce a vicious-circle on this issue by pointing back to the UPGRADE.txt which refers to further documentation ...
So, the UPGRADE.txt says this, users in forums say that, documentation barley sais nothing.
In the german community, they already developed a semantic differenciation between "upgrades" (major) and "updates" (minor) to be able to differentiate things.
PLEASE do add some simple lines of clarification or even better make two chapters for major and minor upgrades.
This can be done in 15 minutes, but will save thousands of users thousands of hours of unnecessary work and frustrations!
Simply updating documentation on drupal.org will not heal the conflict. Only eliminating sources for interpretation within the UPGRADE.txt can do so, which then can serve as a basis for further documentation.
Clear words from the masters are really needed!
Thank you
Bernd
| Comment | File | Size | Author |
|---|---|---|---|
| #6 | UPGRADE.D7.patch | 10.78 KB | Dokuro |
| #4 | upgrade.txtdrupal7.txt | 5.49 KB | Dokuro |
Comments
Comment #1
jhodgdonThis probably applies to Drupal 7 too?
Comment #2
michelleSome related threads:
#295255: Clean-up the upgrade path: UPGRADE.txt
http://drupal.org/node/562796
http://drupal.org/node/881228
http://drupal.org/node/545930
There's many more like that in the forums. There are people out there spending an insane amount of time following the major release upgrade instructions every time a point release comes out.
Heine has a good start on the docs here: http://drupal.org/node/881228#comment-3319314
Michelle
Comment #4
Dokuro commentedWe rewrote the upgrade.txt doc here at the code/doc sprint in Drupalcon Copenhagen. Please review this. Besides clearing up some confusing wording and directions, we addressed the upgrade for contributed modules that have now made it into core and adding a link to a node in the handbook that links to each projects documentation for upgrades. http://drupal.org/node/895314 If this goes ahead I will start creating tasks on each modules page, unless someone else has a better idea about how to handle this better.
Feel free to tear this apart :-/
Comment #5
jhodgdonThat page with the list of contrib modules now included in core - please alphabetize the list of modules! It is very difficult to scan. Thanks.
Regarding your new UPGRADE.txt, please attach a patch so that we can see what has changed. The file you uploaded also needs some copy editing. For instance, I noticed this in the first few lines:
that period on its own line looks very odd. I didn't read through the rest yet. Please file a patch. If you don't know how to make patches, add a comment here and someone else can make the patch.
Comment #6
Dokuro commentedDone and Done
Comment #8
jhodgdonI went back and looked at the proposed revised UPGRADE.txt file that you submitted in #4, and (independent of the patching issues) I have some comments:
a) Formatting - I prefer the formatting/indenting in the original file to the proposed new file. It is much easier to scan, and also when creating the patch, fewer lines will have changed (so we can actually tell what changed) if you keep the current formatting. If you feel strongly about the new formatting, it would be better to reformat in a separate patch so that we know it's a patch that only changes white space.
b) See note in #5 about the period on its own line in the top section.
c) Step 1 - the current UPGRADE.txt says to back up your entire sites directory, and the new file says to back up sites/default. The new file is incorrect in that regard -- the whole sites directory should be backed up. This also applies to step 8 where this information is used.
d) Steps #6 and #7 - you replaced "Drupal installation directory" with "Drupal site root directory" - why? I think that is unnecessarily making the language more technical.
e) Step #8 - removed reference to the "files" directory, which is probably a good thing, except that if someone is upgrading from a really old Drupal site they might still have a files directory around... we should probably say something about that somewhere.
f) Step #9 - this is a problem in both the old and new versions of UPGRADE.txt -- all of a sudden we are talking about a new settings.php configuration file - where was it mentioned how to create this file?
g) Step #10 - you added "Warning: No Drupal 6 contributed modules or themes should be present in any of your
sites directories. As they will not be able to be enabled." For one thing, the second sentence here is not a snetence. For another thing, you are only updating the core database, and all modules have been disabled if you followed the steps above, so having this warning at this step is totally irrelevant.
h) Step #11 in both old and new files - should say "for instance 6.x to 7.x" instead of mentioning 5.x I think?
i) In Step #11 it mentions contributed modules moved to core. That page referenced http://drupal.org/node/895314 is not at all fleshed out, is not really useful IMO except as a list, and it's unlikely that module maintainers are going to add to that page, when it would just duplicate information contained on the module page about how to upgrade (normally you will need to install a D7 stub module that will help you upgrade from 6.x to 7.x). So I would instead leave out that reference and maybe just mention that some contrib modules have been added to D7 core, check the module's project page for more information about upgrading.
j) The final two lines should be wrapped closer to 80 characters. This applies to both the old and new files.
Comment #9
jhodgdonActually, this whole issue is a duplicate of this older issue with a lot of additional ideas:
#295255: Clean-up the upgrade path: UPGRADE.txt
Please continue discussion there.