[sldev] Better build instructions

[Soft]

On Mon, Jul 28, 2008 at 10:03 AM, Alissa Sabre <alissa_sabre at yahoo.co.jp> wrote:
>
> 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.)

And this is the killer. The viewer source gets a lot of first-time
attention once an RC becomes an official release. This is where the
most edits traditionally come in. Meanwhile, senior source users are
starting to document the new RC.


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

The problem is that we've had different people writing with different
approaches. Looking back through history, I see competing edits to
bring it into line with release/, the RC/ branch, and even past viewer
releases.


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

Anyone have suggestions on how to handle this?


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

That's fair. We can make a decision about branching each time an RC is
created. I suspect that most of the time it won't be needed. cmake was
a major disruption, as will be the VS2003 to VS2005 migration. More
often there will be a single library added or removed, or an
environment setting to tweak.