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

[Olaf Wagner]

Quoting 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.

Thank you for this description of your experience. I'll try to address
at least some of the issues during the next days; not sure how far I'll
get.

Some of the problems are still caused by the server crash, where many
old archives were simply lost and haven't been reconstructed until now.
Others are caused by two types of installation archives (legacy format
and Jay's new format), which are both found there. Others are simply
caused by out-of-date documentation, which nobody cares for much :-/

I think it will be best to provide a complete new set of archives, but
this may still take some time, and then update the documentation
appropriately. Progress is much slower than I hoped for (completely
my fault).

Olaf

> 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
>
>



-- 
Olaf Wagner -- elego Software Solutions GmbH
                Gustav-Meyer-Allee 25 / Gebäude 12, 13355 Berlin, Germany
phone: +49 30 23 45 86 96  mobile: +49 177 2345 869  fax: +49 30 23 45 86 95
    http://www.elegosoft.com | Geschäftsführer: Olaf Wagner | Sitz: Berlin
Handelregister: Amtsgericht Charlottenburg HRB 77719 | USt-IdNr: DE163214194