Versioning the language spec on dlang.org

[H. S. Teoh via Digitalmars-d]

Since we're in the middle of many website revamps, here's a good time to
consider this very important issue, as illustrated by somebody asking on
the d-learn forum why dlang.org talks about AA.byKeyValue but the
current release doesn't have such a method.

Of course, byKeyValue is in git HEAD, but since we haven't released the
code yet, what's currently on dlang.org reflects something newer than
most people have access to.

Recently, the policy is that all feature change PRs must be accompanied
by documentation pulls -- which totally makes sense, since we don't want
things to be undocumented. However, pulling these documentation PRs
means that *some* things on dlang.org will refer to features that are
not yet released.

I see two solutions:

1) Don't pull these doc PRs, but mark them for the next release, and
once we finalize the release, pull 'em all and update dlang.org.

2) Version the language docs on dlang.org so that these doc PRs get
pulled into a separate prerelease section of dlang.org, so that people
can have a sneak preview of what's coming, and bleeding-edge git HEAD
people actually have up-to-date reference docs on dlang.org (instead of
having to build their own from git HEAD).  Phobos already has a
phobos-prerelease section, of course, but the language docs currently
don't.

(1) is the easiest way out, of course. But I think (2) is more
worthwhile. It also allows looking back at older language docs (if we
archive the old ones) which might be useful to track how the language
has changed over time.

This issue affects quite a lot of things, actually -- any compiler
changes that affect user-facing interfaces, be it command-line options,
ddoc predefined macros, new language syntax / features, new druntime
APIs like byKeyValue, etc., all require dlang.org changes. They really
need to be versioned properly!


T

-- 
What do you get if you drop a piano down a mineshaft? A flat minor.