Moodle documentation: Continuing on Upgrade docs

Moodle documentation: Continuing on Upgrade docs

by Visvanath Ratnaweera -
Number of replies: 27
Picture of Particularly helpful Moodlers Picture of Translators
@Howard and all

You wrote:
> I've been doing a lot of work on the installation docs recently and the proliferation of different versions is confusing. There is a redirect in place to direct the casual enquirer to the latest version but that does not mean that updates will be made in the latest version. Neither does it mean that updates will be copied back to older versions.

I've stumbled more than once in contradictory or misleading instructions in the set of Upgrade docs, which I don't want to repeat here. For those interested, here is a recent appearance http://moodle.org/mod/forum/discuss.php?d=192326#p840478 (German).

If there are active German translators reading this, I strongly recommend the follow-ups to that post by Bernd Albers, Uwe Krüger and Ralf Hilgenstock. Excellent advice from the "front line"!
Average of ratings: -
In reply to Visvanath Ratnaweera

Re: Moodle documentation: Continuing on Upgrade docs

by Howard Miller -
Picture of Core developers Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Peer reviewers Picture of Plugin developers
Noted - will investigate. I haven't looked at Upgrade docs but I do recall that they could be a lot better.
In reply to Howard Miller

Re: Moodle documentation: Continuing on Upgrade docs

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
The upgrade path 1.9 -> 2.2 (in one step) is officially supported, see http://moodle.org/mod/forum/discuss.php?d=195460&parent=853866. So it is a matter of making the documentation clear.
In reply to Visvanath Ratnaweera

Re: Moodle documentation: Continuing on Upgrade docs

by Helen Foster -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers Picture of Translators

Visvanath, I've just checked the documentation Upgrading and found "Normally you can upgrade directly form any Moodle version to any later version. So, for example you could upgrade from 2.0 to 2.1, or from 1.9 to 2.2." Have you any suggestions how it can be made clearer?

In reply to Helen Foster

Re: Moodle documentation: Continuing on Upgrade docs

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
Hi Helen

No suggestions, sorry. The statement "Normally you can upgrade directly form any Moodle version to any later version ..." is wrong.
In reply to Visvanath Ratnaweera

Re: Moodle documentation: Continuing on Upgrade docs

by Helen Foster -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers Picture of Translators

Ah, I guess you mean the typo - 'form' should be 'from'. smile

In reply to Helen Foster

Re: Moodle documentation: Continuing on Upgrade docs

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
Of course not! That would be nitpicking.

I meant, for example,
- "it will, for the first time, NOT be possible to skip 1.6 and 1.7 on the way to 1.8 from 1.5 or earlier. If you want to go beyond 1.7, you need to "stop" at 1.7 and complete all the UTF-8 migration before continuing.

Moodle 1.8 will actually prevent you with a message if you are upgrading from earlier than 1.6."

Source: http://moodle.org/mod/forum/discuss.php?d=56915#p260315

- "When upgrading to Moodle 2.0, you must have Moodle 1.9 or later. if you are using an earlier version of Moodle (eg 1.8.x) then you need to upgrade to Moodle 1.9.x first."

Source: http://docs.moodle.org/20/en/Upgrading_to_Moodle_2.0


There were plenty of cautious statements on the "from any version to any other" theory in the past. See http://moodle.org/mod/forum/discuss.php?d=56915#p259640 ("It's one of those "Moodle assumptions" that you can upgrade from any version to any other. My only caveat is that the further you jump, the fewer other people have done it before you and the less testing it has had.") or http://moodle.org/mod/forum/discuss.php?d=56915#p259668 ("With any such "skip one major release" upgrades it's paramount to backup your database at the database level. ... Make sure you know how to perform a restore if things go wrong, and that the backup file is good by restoring it somewhere ...")

May be people misunderstood "You should always be able to upgrade from any point on a stable branch to the latest version on that stable branch, so 1.9.2+ -> 1.9.13+ is fine." http://moodle.org/mod/forum/discuss.php?d=182443#p794459


In reply to Visvanath Ratnaweera

Re: Moodle documentation: Continuing on Upgrade docs

by Robert Brenstein -
Possibly, the optimal way could be to display an upgrade grid, showing explicitly from which version to which direct upgrades are possible, augmented with comments.

It is not relevant for this discussion, but your example has a few technical errors (unicode migration is done when converting from 1.5 to 1.6; 1.7 should be skipped altogether, that is going from 1.6 to 1.8 directly is recommended, and only then to 1.9 and further).

Judging from recurrence of upgrade questions, the upgrade instructions from 1.5 and up should continue to be available.
Average of ratings: Useful (1)
In reply to Robert Brenstein

Re: Moodle documentation: Continuing on Upgrade docs

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
Robert Brenstein wrote:
> Possibly, the optimal way could be to display an upgrade grid, showing explicitly from which version to which direct upgrades are possible, augmented with comments.

Yes, that would be very useful. I guess the correct place is http://docs.moodle.org/en/Upgrading.

> It is not relevant for this discussion, but your example has a few technical errors (unicode migration is done when converting from 1.5 to 1.6; 1.7 should be skipped altogether, that is going from 1.6 to 1.8 directly is recommended, and only then to 1.9 and further).

I was quoting Martin D http://moodle.org/mod/forum/discuss.php?d=56915#p260315. It was posted in October 2006, must be outdated. Could you pl. post a follow up with the corrections? Not only because it is linked to docs.moodle.org/en/Upgrading.

> Judging from recurrence of upgrade questions, the upgrade instructions from 1.5 and up should continue to be available.

According to Helen http://moodle.org/mod/forum/discuss.php?d=197602#p861431 that was historically the http://docs.moodle.org/en/Upgrading page. But it has come a long way since then. And the multitude of wikis is not going to simplify the matters either. Sorry, I have no suggesions on how to (re)create this page.
In reply to Visvanath Ratnaweera

Re: Moodle documentation: Continuing on Upgrade docs

by Robert Brenstein -
> Could you pl. post a follow up with the corrections?

I just browsed the docs and found all the info is actually there. It can be found when visiting the upgrading info for admins for Moodle 1.9 and covers versions from 1.5.

About skipping 1.7, see section "Upgrading more than one version" on http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.8 . Same is mentioned on http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.9 .

http://docs.moodle.org/en/Upgrading has links to the individual version upgrade pages, but I believe that it should also have a direct link, and somewhere on top of the page, to http://docs.moodle.org/19/en/Upgrading since that page has a wealth of information about pre-version2 upgrades .
In reply to Robert Brenstein

Re: Moodle documentation: Continuing on Upgrade docs

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
Hi all

To my understanding, the set of Upgrading documents are:
- http://docs.moodle.org/22/en/Upgrading (must for all)
- http://docs.moodle.org/22/en/Upgrading_to_Moodle_2.2
- http://docs.moodle.org/21/en/Upgrading_to_Moodle_2.1
- http://docs.moodle.org/20/en/Upgrading_to_Moodle_2.0
- http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.9
- http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.8
- http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.7
- http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.6
- http://docs.moodle.org/19/en/Upgrading (for < 1.6)
one shoud read in that (reverse) order.

Two things:
1. There is an article http://docs.moodle.org/20/en/Upgrading_to_Moodle_2.1, which is outside this logic. I don't know whether there are more. In any case some people do not appreciate this multitude, see http://moodle.org/mod/forum/discuss.php?d=200153#p873762.
sad

2. The Upgrading docs I've checked belong to the category "Installation". From a system administrators point of view upgrading (an existing) Moodle and installing (a fresh) Moodle are two different things. How about creating a new category "Upgrading"?

In reply to Robert Brenstein

Re: Moodle documentation: Continuing on Upgrade docs

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
I'm sorry, I still need some clarifications:

About skipping 1.7:
- why does http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.8 ask to "Read http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.7 if you are upgrading to 1.8 from 1.6" if version 1.7 is to be skipped?

- same thing in http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.9, "Read http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.7 if you are upgrading to 1.8 from 1.6"?

To skip 1.8 or not:
Robert Brenstein - Tuesday, 6 March 2012, 07:32 AM wrote:
> 1.7 should be skipped altogether, that is going from 1.6 to 1.8 directly is recommended, and only then to 1.9 and further

Petr Škoda - Tuesday, 6 March 2012, 10:45 PM wrote:
> I recommend to upgrade first to latest 1.6.x, then to latest 1.9.x and finally to current 2.2.x

Is there consensus on this? Going from 1.6 to 1.9, should one skip 1.8 or not?

(@Séverin, thanks for pointing this up, in the Installation problems forum, I think)
In reply to Visvanath Ratnaweera

Re: Moodle documentation: Continuing on Upgrade docs

by Tim Hunt -
Picture of Core developers Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Peer reviewers Picture of Plugin developers

Even if you are going to skip a version, like upgrading from 1.6 to 1.9 in one go as recommended, you still need to understant what changed, and whether there are any potential issues to be aware of. Therefore, you need to read all the 1.7, 1.8 and 1.9 release notes.

Average of ratings: Useful (1)
In reply to Tim Hunt

Re: Moodle documentation: Continuing on Upgrade docs

by Séverin Terrier -
Picture of Documentation writers Picture of Particularly helpful Moodlers Picture of Testers Picture of Translators

That's exactly what i had understood, and wanted to mean.

I like when things are clear, and that's not always the case...

Based on informations i had read, i've put this in french upgrading documentation :

1.6 (1.7 or 1.8) -> 1.9 (2.0 or 2.1) -> 2.2 (2.3)

And indicated that version in parenthesis can be skipped, and you must update to bold version !

Séverin

Average of ratings: Useful (1)
In reply to Séverin Terrier

Re: Moodle documentation: Continuing on Upgrade docs

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
@Tim

You wrote:
> Even if you are going to skip a version, like upgrading from 1.6 to 1.9 in one go as recommended, you still need to understand what changed, and whether there are any potential issues to be aware of. Therefore, you need to read all the 1.7, 1.8 and 1.9 release notes.

http://docs.moodle.org/19/en/Moodle_1.7_release_notes, yes. But my subject was http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.7. Indeed it is a summary of major changes and some advice for the Moodle administrator, but not upgrade instructions as such. I appreciate, if the label says what is inside.

Talking of labels, http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.7 is twisted. I always think, how can one "upgrade" Moodle from 1.9 to 1.7!
sad

Anyway, thanks for the answer to the second question, "to skip or not to skip 1.8". I understand the phrase "from 1.6 to 1.9 in one go as recommended" as the official answer, one should _skip 1.8_ going from 1.6 to 1.9.

@Séverin,
OK, the french knew it right from the beginning. But I've learned my lesson from Alice, I'd pass.
smile

‘Perhaps it doesn’t understand English,’ thought Alice; ‘I daresay it’s a French mouse, come over with William the Conqueror.’ (For, with all her knowledge of history, Alice had no very clear notion how long ago anything had happened.) So she began again: ‘Ou est ma chatte?’ which was the first sentence in her French lesson-book. The Mouse gave a sudden leap out of the water, and seemed to quiver all over with fright. ‘Oh, I beg your pardon!’ cried Alice hastily, afraid that she had hurt the poor animal’s feelings. ‘I quite forgot you didn’t like cats.’ (continue to the end of the chapter)

http://ebooks.adelaide.edu.au/c/carroll/lewis/alice/chapter2.html
In reply to Visvanath Ratnaweera

Re: Moodle documentation: Continuing on Upgrade docs

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
I went through the upgrade documentation again, and found:

"If upgrading from earlier than 1.6, we recommend upgrading to 1.6 first, then 1.8 -> 1.9"
http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.9#Notes

So skipping 1.8 not official yet?
In reply to Visvanath Ratnaweera

Re: Moodle documentation: Continuing on Upgrade docs

by Robert Brenstein -
If I recall, there was something with introducing roles that made going through 1.8 important for at least some sites. That might have been addressed in later versions of 1.9 thus creating this seemingly contradictory advisory.
In reply to Robert Brenstein

Re: Moodle documentation: Continuing on Upgrade docs

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
Hi Robert

You wrote:
> there was something with introducing roles that made going through 1.8 important for at least some sites.

May be you mean this:
"In general, it is recommended to upgrade via each version of Moodle, for example 1.7 -> 1.8 -> 1.9. An exception to this is when upgrading from 1.5 or 1.6, when it is recommended that 1.7 be skipped, in other words upgrade 1.5 -> 1.6 -> 1.8 -> 1.9. (The main reason for this recommendation is that the default roles settings obtained when upgrading to 1.7 are not ideal for 1.8 onwards.)"
http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.9#Upgrading_more_than_one_version

> That might have been addressed in later versions of 1.9 thus creating this seemingly contradictory advisory.

I have no idea. This note is up to date, for example:
"If you are upgrading from a pre-1.6 version it is recommended that you upgrade first to the latest 1.6.x, then to the latest 1.9.x and finally to the latest 2.x. See Petr's forum post Re: Continuing on Upgrade docs for further information."
http://docs.moodle.org/22/en/Upgrade#Upgrading_more_than_one_version

Well that refers to http://moodle.org/mod/forum/discuss.php?d=197602#p861964 - this very discussion!
In reply to Visvanath Ratnaweera

Re: Moodle documentation: Continuing on Upgrade docs

by Robert Brenstein -
Your quote explains why 1.7 should be skipped but says nothing about 1.8. However, roles might have been it. I seem to vaguely recall some issues with setting up roles by 1.9 when coming from pre-1.7 versions. As I said, this might have been (and probably was) fixed in later 1.9.
In reply to Robert Brenstein

Re: Moodle documentation: Continuing on Upgrade docs

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
Hi Robert and all

Whatever Moodle Docs say, can we agree that the recommended path for going from 1.6 to 1.9 is a straight (one step) upgrade? I just want to avoid giving contradictory advice on help forums.
In reply to Helen Foster

Re: Moodle documentation: Continuing on Upgrade docs

by Petr Skoda -
Picture of Core developers Picture of Documentation writers Picture of Peer reviewers Picture of Plugin developers
Hi,

I recommend to upgrade first to latest 1.6.x, then to latest 1.9.x and finally to current 2.2.x

If you use other versions you may need to manually fix some settings or tweak the roles, you will not loose any data but the upgrade results may not be the same exactly.

The unicode migration was a bit tricky, if you did not use languages with incompatible encodings it is usually a lot easier to export 1.6.x SQL dump from your database, convert to utf-8, fix some broken chars and then import into fresh new database with utf-8 defaults. The built-in conversion did not work for me much (Czech language).

In any case BACKUP, BACKUP, BACKUP (database & dataroot dir) and use a test server for the actual upgrade.

Ciao
Average of ratings: Useful (5)
In reply to Petr Skoda

Re: Moodle documentation: Continuing on Upgrade docs

by Helen Foster -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers Picture of Translators

Visvanath, thanks for explaining what you meant.

Petr, thanks for your recommendation which I have added to Upgrading.

In reply to Visvanath Ratnaweera

Re: Moodle documentation: Continuing on Upgrade docs

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
In reply to Visvanath Ratnaweera

Re: Moodle documentation: Continuing on Upgrade docs

by Mary Cooch -
Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Testers Picture of Translators

Well the upgrading to 1.6 is here -  http://docs.moodle.org/19/en/Upgrading_to_Moodle_1.6

I haven't found the 1.5 - I think that's been deleted.

In reply to Mary Cooch

Re: Moodle documentation: Continuing on Upgrade docs

by Helen Foster -
Picture of Core developers Picture of Documentation writers Picture of Moodle HQ Picture of Particularly helpful Moodlers Picture of Plugin developers Picture of Testers Picture of Translators

Mary, the reason why you can't find any documentation on upgrading to 1.5 is because it never existed! Version-specific upgrade documentation began with 1.6 when Moodle Docs began.

Visvanath, thanks for pointing out the need for version-specific upgrade documentation links. I've added a list of them to the see also section of Upgrading.

Average of ratings: Useful (1)
In reply to Helen Foster

Re: Moodle documentation: Continuing on Upgrade docs

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators
Hi Helen

You wrote:
> Visvanath, thanks for pointing out the need for version-specific upgrade documentation links.

Did I say that?

I said:
a) there is (was) an ambiguity in the Upgrade docs

b) a one-step upgrade 1.9 -> 2.2 is officially supported (by quoting Tim)

c) that there _were_ docs http://docs.moodle.org/en/Upgrading_to_Moodle_X.Y in the past, which you have corrected to say that there was only a single document, http://docs.moodle.org/en/Upgrading ?, for all versions upto 1.5, and the pattern Upgrading_to_Moodle_X.Y started with version 1.6.

d) If those old documents are still around, that'll make the life easier for some visitors to 'Using Moodle'.

I didn't talk of a (new) need.
In reply to Visvanath Ratnaweera

Upgrading documentation has changed the concept?

by Visvanath Ratnaweera -
Picture of Particularly helpful Moodlers Picture of Translators