[sldev] Better build instructions

[Alissa Sabre]

> I see no problem with a new build page for each viewer release.
> Re-editing the same page over and over for each release means that
> historical build information may become lost or overwritten as time
> passes.

I don't think so.

We are using Mediawiki, so all past versions of a page are always
available through _history_ tab.  Historical build informations are
never lost.  We "re-edit the same page over and over", keeping older
versions.

I primarily support just rewriting a same instruction page over and
over to synchronize with the latest source.  That's what I've been
doing in the past.

One problem of using Mediawiki history is that it is unclear which
wiki version corresponds to which source version.  I'm trying to add
some words on source version when editing build instruction pages
(e.g., "in version X.X", "after version X.X", or "this doesn't apply
X.X or later", etc.).  I have once added an explicit link to an older
version of the page (something like "This page is on version X.X or
later; see XXX for previous versions," with XXX is a link to an older
version of the page.)

It may be my fault that I didn't say it explicitly since then, and
this policy is not widely accepted by the community.  (Although it is
possible that many people recognized my convention and they simply
don't like it.)

> It takes about 30 seconds to edit the current (old) build page, copy
> the text, make a new page for the next viewer, paste, and then update
> this new page to make note of any changes.

Please don't do it, even if it is handy for you, because:

- If you edit an existing page, Mediawiki's built-in compare function
  shows your changes very easily.  However, if you copy the content
  and rewrite slightly, it will be very hard for other people to find
  what change you made over the previous version.  It is especially
  true for a developer who has build previous versions and wants to
  know what is the difference for the latest version.

- It makes maintaining other language versions (translations) of the
  page very hard, partly because it is hard to find changes (see
  above), and partly because you probably don't copy the corresponding
  translated pages.

On the other hand, a big disadvantage of using Mediawiki history
feature for the build instruction for past versions of viewer source
is that Mediawiki doesn't allow editing of the history; editing of a
page is always on the latest version.  (Mediawiki's version control
mechanism provides no _branching_.)  So, it is hard (or almost
impossible) to keep both pre cmake instructions and cmake instructions
up-to-date during the transition period (and both the pre and post
cmake build process are changing...)

Under this situation, I have no objection to have two separate pages,
e.g., building instructions for traditional and cmake-based
environments.  

    Alissa Sabre

--------------------------------------
Power up the Internet with Yahoo! Toolbar.
http://pr.mail.yahoo.co.jp/toolbar/