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.

On Sunday, 25 January 2015 at 00:53:11 UTC, H. S. Teoh wrote:
>
> 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.

How about moving them into the dmd repo? This has the advantage that language changes can be done in one pull (implementation, tests and documentation), and we can reuse the same technique as for Phobos to build stable and pre-release docs.

On 1/24/15 4:50 PM, H. S. Teoh via Digitalmars-d wrote:
> 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.

This is quite easy to do by using tags. Currently we use tags to build the latest and prerelease versions of Phobos - see LATEST-related code in posix.mak.

Should be easy to pull the LATEST tag from dlang.org and put that in the main site, and redirect the current into e.g. dlang.org/new or something.


Andrei

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