[M3devel] Getting ready for new users (Re: HEADS UP: Release engineering)

[hendrik at topoi.pooq.com]

On Tue, Apr 14, 2009 at 01:11:33PM -0400, hendrik at topoi.pooq.com wrote:
> On Sat, Apr 11, 2009 at 11:26:11AM +0200, Olaf Wagner wrote:
> > 
> > I'd rather avoid creating a branch too early, as that means more work
> > by selecting and merging fixes from trunk to branch. So here my questions:
> > 
> >  o Do we all agree on a temporary code freeze?
> >  o When should we start? I.e. wha changes would you like to complete
> >    before we start the release process?
> 
> One thing that's essential is to debug the documentation -- 
> specifically, the installation instructions, the various README files, 
> and so forth.  A naive user. competent in the ways of computers, but not 
> yet in the ways of Modula 3, should be able to follow the instructions 
> and succeed.

In a previous post, I emphasized that it was important for the 
installation instructions to be usable by a prospective user of Modula 
3.  If he has trouble installing it, he'll never get around to 
discovering its practical advantages over C.  So I decided to play the 
part of a naive user, and thereby to make it clear what, if any, 
obstacles he would encounter.  Here are my results.  When these problems 
are cleared up, I have real naive user in mind whom I'll ask to install 
Modula 3 on his system, keeping a log of difficulties.

I hope you'll take this in the spirit it was intended, as a form of 
constructive criticism, as a bug report, not as a rant.



I started pretending I had just heard about Modula 3 and decided to try 
it.  So I did the obvious and looked for Modula 3 on googlee.  I found 
www.modula3.org.

It had a link to the download page (second or third message in main 
panel)

Because of advice there to get the latest patch level, tried to download 
current development snapshot CM3 d5.5.0 -- no such thing, link broken.

Went to look for current stable release.
Went to installation instructions
Went to more specific instructions for Ubuntu or Debian (I am running 
Debian squeeze).  Noticed that the instructions mentioned Ubuntu 
everywhere, but rarely Debian.

established my ownership of /usr/local

install flex and libncurses5-dev
install libpq-dev, freeglut3-dev,unixodbc-dev, libmotif-dev, libx11-dev

installed stow to manage symbolic links

stow was kind of complicated, so I used the ln -s as in the instructions 
to link libXmu.so and libXaw.so.

Now download.

The link to opencm3.net didn't point to a page containing obvious 
downloads of tar archives.
But its installation link pointed to a page with a download link, which 
led to a pane that contained downloadable looking links far down the 
page

The link cm3-min-POSIX-LINUXLIBC6-d5.5.0.tgz led nowhere.

But cm3-min-POSIX-LINUXLIBC6-5.4.0.tgz seems OK

It seems my browser chooses which directory to download to; mine chose 
~/Desktop without telling me, which occasioned a bit of a search.

Go back to the instruction page, where I discover that "most earlier 
minimal binaries do not work, so stick with d5.5.1 or later.  These are 
known to succeed:
 then a few .tgz file names, which are *not* links."  So time to discard 
what I've just downloaded.  But where am  I to find the one that works?

At this point the naive user would start to get annoyed.
But there were several other links immediately above this warning.  
Maybe it's time to try them.  Why was I first directed to 
www.opencm3.net then, and not to one of the other directories more 
directly?

try http://www.opencm3.net/download.html
  It looks like I've been here before.
  Under current development snapshots there's a d5.5.0 link, but that's 
too old.

follow the uploaded archive page:
find a cm3-min-LINUXLIBC6-d5.7.1.tar.gz
That's a lot more recent, and it leads to an actual fila!
remove the obsolete one, to avoid confusion later.

But there's no checksum for the new one on the checksums page, 
http://www.opencm3.net/checksums.php3.  I guess I'll just assume I 
downloaded it correctly.

The untar command from the installation instructions created a directory 
cm3-min-LINUXLIBC6-d5.7.1 within ~/cm3-min.  This means that the next 
command, ./cminstall will not work.

Nor is there a cm3install inside ~/cm3-min/cm3-min-LINUXLIBC6-d5.7.1 or 
anywhere else in sight.

The would-be user is now thoroughly stymied.

If he were to persist, he might do so by posting a message like this in 
the comp.lang.modula3 newsgroup.  Does anyone still read that?

-- hendrik