[Moin-user] Failed to update MoinMoin from 1.2.3 to 1.3.1 and being disappointed :-(

[Ulf Lamping]

Thomas Waldmann wrote:

>> Some examples qouting the migration file:
>> "To start, copy your data/ directory to this directory" What is this 
>> directory?
>
>
> To be exact:
> """
> To start, copy your data/ directory to this directory and then start 
> with the script according to the table above and also run all scripts 
> with a higher number - one after the other, in ascending order.
> """
>
> Ok, it could be clearer, but of course the directory where the scripts 
> are located is meant. It also talks about those scripts in the 
> paragraph before...

But that's exactly the parts I have problems with. You *assume* that I 
*know* what you mean. Why not writing it down to be bullet proof?

"To start, copy your data/ directory to the directory where these 
scripts reside and then start the scripts xyz in that dir"

Please don't assume too much about the knowledge of your users. For 
example: I'm an experienced C programmer, but I don't have a lot of 
knowledge about python and how to use python scripts.

> Maybe this was because this file was located in the scripts directory 
> when it was written and moved out of there to toplevel dir later.

That would explain the "this dir".

>> The migration file doesn't even mention that you have to replace your 
>> moin.cgi file and maybe other files too (I've found that info 
>> somewhere in the CHANGES file).
>
> README.migration only talks about migrating the data from 1.2 to 1.3, 
> not about moin setup. And yes, you have to read CHANGES.

I did read the text:

"Those are some scripts that convert your wiki data to the current MoinMoin
version. You must use them AFTER stopping your old wiki code and BEFORE
starting your new wiki code."

to mean the seepration of the wikis data and the wiki program part. I didn't noticed that you see the cgi part is a third "program part".

Adding something like: "This will *not* update your wiki cgi scripts which did changed too. Please have a detailed look at the CHANGES file." might help a bit. 
Although a step-by-step guide would've probably explained it a lot better.

>> As I've observed by other projects too, developers seem to think it's 
>> enough to write good programs, but it itsn't. It's also very 
>> important to write good documentation, as user's have to be able to 
>> *use* software. And of course, making the program as easy to use as 
>> possible is always a good idea. Yes, I know that writing 
>> documentation isn't fun, but it has to be done.
>
> No doubt about that. But you what's the problem simply asking what you 
> didn't understand? Either here or more real-time on IRC on #moin?

I don't use IRC very often, so I prefer "oldstyle" mailing lists.

>> I'm now at a point, where I actually thinking about moving to a 
>> different wiki software, although I like the MoinMoin wiki engine.
>
> That won't make conversion easier (but the contrary).

Well, yes but only one time. Hopefully other wiki engines provide an 
easier update path. And of course, I'm writing this to help improve the 
next MoinMoin release update being more user friendly.

> And you still will have to read all DOCs on major updates.

I'm used to automatically done that for me on a lot of other programs. 
You might know Ethereal (www.ethereal.com) where I'm one of the 
maintainers and we are thinking often about easy and reasonable ways to 
provide default values and such, and yes I have to do similiar 
discussion there too. I really do understand that you don't provide such 
conversation functions for every step in the developer versions.

But a good conversion function between released versions is really a 
*must* in my eyes.

>> don't want to go through that kind of update process again spending 
>> hours to update to a new MoinMoin program version. I thought that the 
>> days of such a script and configuration hell is over.
>
> Migrating from 1.2 to 1.3 is more effort that from 1.x to 1.2 (or 
> 1.2.3 to 1.2.4). It is just because there where major changes in how 
> it internally works. We even documented that it is more effort and I 
> don't know how often I wrote "READ CHANGES" all over the place.
>
> Believe me, we don't do that for fun or to annoy users, but because of 
> making it work better and open doors for new features.

Of course, I believe you don't do that to annoy people. BUT, if you do 
such things, think about how you can easily guide your users through 
difficult upgrade processes. Today I don't think it's an option to tell 
people "just read all the docs lying around and if you still have 
questions e-mail us".

>> Currently I'm thinking to go back to the backup of my content, bring 
>> up the 1.2.3 version back to life
>
> Was that directory question the only thing you didn't find out?

It were a lot of minor things which was difficult to understand in the 
docs, making it hard to get the overall job done.

Why not providing a step-by-step guide to upgrade an installation from 
one release to the next one? Take the user by the hand and he/she will 
be pleased to follow :-)

> If not, why don't you just ask your questions?

I'm used to solve problems using documentation, as this usually lead up 
to learning a lot about the thing I'm working with.

> > and convert the content to some other
>
>> wiki engine and stop using MoinMoin :-(
>
> Feel free. We don't force you to use moin. :)

Hmmm, you're not working for microsoft? ;-)

>> '/cygdrive/d/ulfl/etc/Moin/mywiki/D:\ulfl\etc\Moin\mywiki\data')
>
> That looks somewhat strange!?

Well, yes I think that's really strange.

>> Apache/2.0.52 (Win32) Server at 127.0.0.1 Port 80
>
> There is some known Apache2 and IIS CGI brokenness under Win32 
> affecting pages with non-ASCII page names. See MoinMoin:MoinBugs.
>
> It is not a moin bug and it works with Apache 1.3/Win32 and also with 
> Apache1 and 2 under Linux.

Didn't noticed any problems with that configuration until now.

>> parser.wiki: link formating ... FAIL
>> parser.wiki: escape html markup in getText formatted call with link 
>> ... FAIL
>> parser.wiki: escape html markup in getText formatted call ... FAIL
>
> I think you can just ignore those.

If I can ignore these, why are they in such a test script, making users 
just feel uncomfortable? Just remove those tests, or put a remark in the 
script that "if these outputs might fail just don't care, they are just 
informational".
BTW: if these tests might fail, what is the use of such? Why not remove 
them or put them into some "developer only" related unit tests?

> Maybe just join #moin next time you try (if you try).

Well, as written above I don't use IRC often.


After all, I wanted you to understand the importance of good update 
functions and understandable and accurate documentation about it. In my 
experience this is *really* important for a successful project and an 
important part of product quality!

I really don't think that upgrading from one release to the next should 
end up in: read all the docs you can find, assume some parts not 
explicitly mentioned and go and run several scripts on your data 
hopefully end up with a new installed version. Ah yes, and by the way 
tweak some of your configuration scripts by hand.

It's really only an excuse to do it that way, being lazy not to find a 
good way to automatically doing such things (I know that's really hard 
work). Of course, there a special circumstances where an automatic 
update process cannot be done (and will fail), but that should be the 
exception and not the rule.

Come on, it cannot be the preferred way to do such things! Don't think 
about improving small parts, it's the major way that has to be improved.

What I would like to see is the following update manual:
1.) stop your current wiki instance (Apache, ...), see 
http://moinmoin.wikiwikiweb.de/HelpOnStop
2.) update your MoinMoin installation by simply installing the new 
version over an existing one, simply follow the instructions in 
http://moinmoin.wikiwikiweb.de/HelpOnInstalling
3.) update your wikis data by copying update.py into your wiki data 
directory and call "python update-py"
4.) test your installation 
http://moinmoin.wikiwikiweb.de/HelpTestAfterInstallation for the various 
installation alternatives
5.) use your new wiki installation :-)

Please notice me if you see it differently and things on that part won't 
improve significantly in the next featured release.

Regards, ULFL