Transitioning std lib modules/packages

[Jonathan M Davis via Digitalmars-d]

On Friday, November 25, 2016 11:10:51 Andrei Alexandrescu via Digitalmars-d 
wrote:
> The recent discussion about std.random suggested that we need a
> transitioning scheme for certain modules and packages in std that
> provide different designs without breaking the existing ones.
>
> C++ has things like std::tr1 and #if __cplusplus >= 201103L. We also
> need to have separate names for modules that are redone with
> incompatible APIs, such as std.random or std.json. For a while now I was
> thinking along the lines of std.v2.random, std.v2.json etc. but that is
> misleading - it suggests the entire std has a v2 version from which we
> pick some specific modules. In reality, it's only specific modules that
> have a v2 version. So I have a low-tech idea and a high-tech one:
>
> * Low-tech: just use std.random_v2, std.json_v2, etc. Leave std.random,
> std.json etc be and put them in maintenance mode. Possibly deprecate
> them later if the v2 versions work great.
>
> * High-tech: use std.random.v2, std.json.v2, etc. This entails more
> administrative work (convert modules to packages etc) but may have some
> advantages due to the version being a separate symbol instead of
> embedded in the name.
>
> So I'm leaning toward the low-tech approach unless evidence comes up
> that the other is better.
>
> The clear message here is that we do need to make good strides toward
> replacing artifacts that need replacing without being crippled by
> backward compatibility.
>
> So if Ilya wants to merge his random work (heh) into std, he would start
> with std.experimental.random_v2, and then upon approval move that to
> std.random_v2.

Two other alternatives:

1. Move std/json.d into std/json/package.d, and then add the new stuff as
modules in std/json/ but don't have std/json/package.d publicly import
anything from std.json.*. It would have the advantage of not breaking any
code while allowing us to still use std.json longterm. The downside is that
you couldn't import std.json and get the new stuff until the old stuff had
gone through the whole deprecation process, and it could be confusing in
that normally, when something is both a package and a module, importing the
module imports the whole package, which it wouldn't do in this case for a
couple of years.

2. Make the new json be something like std.data.json. We'd already talked
about doing that before. Then the new xml stuff could go in std.data.xml. It
avoids the whole v2 thing by further reorganizing Phobos in a hierarchical
manner.

In the case of std.json, I definitely favor going with the std.data.*
suggestion, since I think that it's cleanest, and it avoids the whole v2
problem altogether. Unfortunately, that still leaves the std.random problem,
since I'm not aware of an equivalent to std.data.* for std.random nor is
there any organizational reason AFAIK to put it somewhere else in the
hierarchy.

So, for std.random, I don't know. The "high-tech" approach has problems
similar to my first alternative with regards to confusion of importing
std.random vs std.random.v2, but it's not as bad with the high-tech
approach, because it's clearly in a sub-package/module rather than
effectively being directly in the same package and getting different
versions based on whether you import the package or the individual modules.
That being the case, std.random_v2 is probably better, but it just seems
ugly IMHO. Then again _any_ solution with v2 is ugly. Long term, we could
alias it to std.random, but we'd have to leave the v2 there or be needlessly
breaking folks code just for a name change. So, the "low-tech" approach is
probably best when it doesn't make sense to move it somewhere else in the
package hierarchy, but I don't particularly like it, and in the cases where
it makes sense to move the module to make it more hierarchical (as seems to
be the case with json and xml), then I favor that approach.

- Jonathan M Davis