Jump to:
| Project: | Documentation |
| Component: | Correction/Clarification |
| Category: | task |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed (fixed) |
Issue Summary
I think it is a very good idea
to give a proper placement to the info about
- updating contrib modules
- from 5.x. -> 5.y and 6.x -> 6.y and
- from 5.x. -> 6.x
- same for 4.x if neded
and
- upgrading Drupal core from 4 -> 5 -> 6
much like a recent issue about "Separating the install guide" [345227] I feel that it will be best if update upgrade guide is a separate top-level section - after the installation guide section.
In the moment of writing there is this "Upgrading from previous versions" page near the end of that book. But it has several flaws:
- one expects info about updating Drupal modules and core from an end-user point of view... instead the first links given point to the devel handbook and info about how to upgrade(port) the code of a module...
- there is a link in the end giving info about upgrading core - but nothing is said about updating contrib modules
I think of a section named "Update and upgrade guide" - with sub-pages about all kinds of upgrades and updates - core/contrib and 4, 5,6,7 versions .... Sth like:
Update and upgrade guide
Update or upgrade Drupal core (either one page for all cases or:)
Update Drupal core - same major version - Z.x to Z.y
Upgrade from 4.x to 5.x
Upgrade from 5.x to 6.x
Upgrade from 6.x to 7.x
Update or upgrade a contributed module (again maybe if all is on one page it will be easier to maintain and to say things only once)
Update a module - same major version - Z.x to Z.y
Upgrade from 4.x to 5.x
Upgrade from 5.x to 6.x
Upgrade from 6.x to 7.x
I checked - the right place for this is into "Getting Started" book.
The now existing
- http://drupal.org/upgrade/ - Getting Started > Upgrading from previous versions
and
- http://drupal.org/update/modules - Developing for Drupal > http://drupal.org/update/modules
are misleading to a user seeking info on how to update his/her contrib modules cause the 1st sends the user to the second which in turn is for developers....
And I think the Getting Started > Upgrading from previous versions > Introduction to upgrading
page is quite long and needs cleanup.
What do you think?
PS. It all started when I googled for "drupal update module" - and struggled to find the right page with the right update sequence - http://drupal.org/node/142767#comment-950446
So, to confirm, you would recommend the following?
Upgrading modules while doing a major Drupal version upgrade (e.g. Drupal 5 to 6):
1) Download the latest version.
2) Unzip it.
2.5) Disable old module through admin panel
3) Delete the old module + folder.
4) Replace old with new on server.
4.5) Re-enable the new module through admin panel
5) Run update.php to update the database
vs. Upgrading modules when not upgrading Drupal:
1) Download the latest version.
2) Unzip it.
(do not disable the old module)
3) Delete the old module + folder.
4) Replace old with new on server.
5) Run update.php to update the databasePS2. So after we generally get the book section on updates right, we should look into what pages google gives when doing "drupal module update" and such - e.g. the Update Status module is always in the top 3 results - so putting a link to the general update docs in its project intro is a nice idea...
Respect, rsvelko.
Comments
#1
I just found that http://drupal.org/node/197247 deals with the upgrade docs - thought it would be nice if we sum up the experience from there.
Both issues are not duplicates though. The current one is about better placement and docs uncluttering so it seems an easier one. While http://drupal.org/node/197247 is a issue meant to remind us to regularly update the upgrade docs - cause new versions of Drupal continue to come into this world...
#2
I fixed the link text on the opening page to make it clear that the developer page link is only for upgrading custom modules, not upgrading contributed modules. However that doesn't address what I think is your main point: that it's not clear where to find information about upgrading contributed modules and that the updating section is generally not well structured. More work does need to be done.
#3
I've rewritten the opening - now it is clearer. What do you think, Lee?
@all:
Am I going in the right direction? Is it OK if I freely edit that section according to my plan above?
I am still not a doc team member so I can only edit and not rearange.
#4
I've made a few edits to that page - most significant is probably the links. For custom modules I used the dev guide page for updating custom modules and for themes, there's a section in the theming guide.
Re. your structure, I haven't done a lot of upgrading myself, but I'm wondering if we actually need separate pages for 4 to 5, 5 to 6, 6 to 7 if the procedure is basically the same?
#5
Well first of all I think we need to be clear on the terms. Currently there is a mishmash between upgrade and update. Typically, in Drupal, *update* == code updating and *upgrade* == upgrading your site to the next version, but it isn't applied consistently and starts the confusion (e.g. we have UPGRADE.txt but you run update.php to actually upgrade your site). I don't know what the answer is but we need to make sure we are being consistently clear about which operation is being referred to: code or site.
OK, with that off my chest, I agree with Lee that upgrading your site (both core and contrib) is essentially the same process and has been for a while, so making different version paths isn't necessary. That is only necessary for code updates in the developer/theme sections. So I would say that the textual changes to the upgrade landing page making it clear what the upgrading section is about (and if you are updating code - go there) are good. Structure-wise I think that this works:
Upgrading
- Introduction to upgrading (covers overall concept/steps and the backups) * maybe a different name? Before you upgrade?
- Upgrading Drupal core
- Upgrading contributed projects
- 4.6.5 and prior versions
I've just reordered some of the GS guide and I feel like it is OK as is now, though definitely we can keep messing with it. I don't think that Upgrading should be right after Installing since that is less a GS thing to begin with than a "proper care and feeding down the road" kind of thing. I'm open to discussion on the best order though. Do keep in mind that the GS guide is getting a major overhaul generally right now so things will probably end up shifting around a lot before the dust settles, so I don't want to get too hung up on that point right now.
#6
yes, saw this one - #199388: Documentation lacks an information architecture - newcomers read there too.
#7
Hello !
As statted upper by other members, I also think it lacks a clear documentation about updating contributed modules on Drupal.
This documentation should be accessible from :
- http://drupal.org/upgrade/
- http://drupal.org/update/modules/ (in order to redirect the user who confuses the documentation for user and the documentation for developper).
Currently, documentation about upgrading Drupal is easy to find, but documentation to upgrade "contributed modules" seems to be inexistant AFAIK.
Many thanks in advance for the documentation improvements ! :-)
#8
I've done a bit more work on this. Mostly moved all the pages that were children of the Introduction page to be children of the top upgrading page. I've also moved the pre 4.7 section to the archive.
The section could still use some streamlining.
#9
Yep, needs some cleanup, but we're getting there. Originally I wanted to keep all of the old upgrade docs since some people are still stuck on very old versions - there was just a forum post recently about a guy who inherited a 4.5 site. Upon reflection though, it really would be better for them to rebuild and import content then to try to do the whole upgrade path from that far back. We should at least have a page/mention somewhere to direct people what to do if they are coming from an ancient version of Drupal, i.e. prior to 4.7.
#10
See also #356830: Document the removal of drupal.module in 6.x and site_network module, I think?
#11
this looks pretty well sorted to me - the links lee added to the /upgrade page help, and the /update/modules page is pretty clearly oriented to developers. additionally, with the big changes coming with the update module, this process will change significantly and need to be overhauled again.
#12
Automatically closed -- issue fixed for 2 weeks with no activity.
#13
Sorry for reopening this one. I just wanted to find the documentation about module upgrading because I wanted to point a newbie to it. This was a very hard task btw.
I finally found this page: http://drupal.org/node/250790 which obviously misled this user http://drupal.org/node/856636#comment-3287910.
Is somewhere documented that to upgrade the module you only have to delete the old folder, put the new one in and run update.php? Do all this while logged in as User 1 and while the site is under maintenance. Easy, breazy.
If so, it is not easily discoverable.
I am not comfortable with the book system and I don't want to clutter the docs even more so I did not change anything but I think this part needs an overhaul.
#14
- updating modules in the developers guide: http://drupal.org/update/modules
- updating/upgrading core: http://drupal.org/upgrade
- updating modules for end users: http://drupal.org/node/250790
looks like it's all here, marking fixed.
#15
Automatically closed -- issue fixed for 2 weeks with no activity.