Versioning the language spec on dlang.org

[Jacob Carlborg via Digitalmars-d]

On 2015-01-25 01:50, H. S. Teoh via Digitalmars-d wrote:
> 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!

2) Is preferable.

-- 
/Jacob Carlborg