Add compatibility index for modules

[wilzbach]

After my intent to move outdated modules to undeaD failed, here's the suggested way of documenting old modules.

Great, I think starting with documentation should be the official way of implementing all deprecations.

tl;dr: This generalizes the deprecation warnings (and makes them look nicer than for std.xml).

As suggested this is heavily inspired by the way NodeJS marks their modules, but why not learn from successful ideas?

The overview page:

In practice:

Deprecated

$(COMPATIBILITY_BOX_0)

Experimental

$(COMPATIBILITY_BOX_1)

Stable

$(COMPATIBILITY_BOX_2)

And all in one:

CC @MartinNowak @CyberShadow @andralex @JackStouffer

[dlang-bot]

Thanks for your pull request, @wilzbach!

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

[CyberShadow]

IMHO we don't need the stable markers or the compatibility index. The deprecated/experimental warnings, as they appear in your compatibility index screenshot, look great though - how about using those as is on the modules themselves?

[andralex]

We must have a "Stability: Obsolete" which predates deprecation. It means the code works and does not issue deprecated warnings but a superior solution (EXISTING!!!) is preferred for new code.

[wilzbach]

We must have a "Stability: Obsolete" which predates deprecation. It means the code works and does not issue deprecated warnings but a superior solution (EXISTING!!!) is preferred for new code.

Sure that should be easy enough:

(also added it to the PR)

IMHO we don't need the stable markers

Well, just because I add the macros here, doesn't mean that we need to apply all of them for Phobos.
However, it could be helpful to ensure to people that the module they use is rock-solid... (in theory 😆)
I don't feel strongly about the stable markers, I want to mark old modules ;-)

or the compatibility index.

I guess some people want to know what e.g. "Obsolete" means precisely, but there's no point in always showing the long text. Is this page hurting us?

[CyberShadow]

I guess some people want to know what e.g. "Obsolete" means precisely, but there's no point in always showing the long text. Is this page hurting us?

No, but it seems redundant. I don't think the boilerplate is an issue. Also, the box itself would be a good place to mention the recommended replacements.

[CyberShadow]

However, it could be helpful to ensure to people that the module they use is rock-solid... (in theory 😆)

I'm thinking, modules which may seem well designed today may not appear so 10 years from now :)

[andralex]

One other thing: for each artifact we should be able to automatically get the version that introduced it and (for removed ones) the version that made it unavailable. Perhaps a topic for a different PR.

[CyberShadow]

One other thing: for each artifact we should be able to automatically get the version that introduced it and (for removed ones) the version that made it unavailable. Perhaps a topic for a different PR.

That shouldn't be too difficult. What to do with the result, show it on dlang.org for all symbols somehow?

[andralex]

Yes, it should be easy as people browse some library artifact to get extra info about it including this version stuff.

[adamdruppe]

On Wed, Jun 28, 2017 at 10:57:50AM -0700, Andrei Alexandrescu wrote: One other thing: for each artifact we should be able to automatically get the version that introduced it and (for removed ones) the version that made it unavailable. Perhaps a topic for a different PR.

I think we should also use the `History:` section in ddoc to document changes so like "argument foo introduced in June 2017"... generating it automatically would be good for many things but going forward we could just add it in after merging PRs.

[wilzbach]

Also, the box itself would be a good place to mention the recommended replacements.

Good point. I also removed the "Stability X" everywhere and replaced them with their respective name as the numeric scale is confusing and we can easier extend / modify this scheme without numbering.
Do you know a Ddoc trick to display the separator only if there's a message?

I think we should also use the History: section in ddoc to document changes so like "argument foo introduced in June 2017"...

We probably want to write 2.075?

generating it automatically would be good for many things but going forward we could just add it in after merging PRs.

Yep, I think this "naive" approach will be a lot easier and can be done once on every release by simply going over the changelog. We just need to remind people to add their changes to the changelog (or respective Bugzilla issue), but hopefully the Dlang-Bot is now loud enough ;-)

[wilzbach]

So @CyberShadow are we all happy with DEPRECATED, OBSOLETE, EXPERIMENTAL and STABLE to be stability categories? Of course, we can always extend them, but I would like to continue with my goal and document the old & ugly modules in Phobos. Most likely, during this process, we might rework this category schema anyways ;-)

[CyberShadow]

Arghhh, GitHub ate my comment again.

Generally speaking this change has a larger scope so it's more up to the BDFLs than me to set the direction, but since you asked for my feedback:

DEPRECATED, OBSOLETE, EXPERIMENTAL

These seem fine to me.

I don't think we need stable.

Some are so proven, and so relied upon, that they are unlikely to ever change at all.

Can we really say that about anything? :) We change / deprecate things even in relatively new modules.

This feature is subject to change, and is gated by a command line flag

Seems like there are some conflicting goals here - nothing in Phobos is gated behind a compiler flag. Is the intent to use these macros in the spec as well?

Still not sure about the compatibility index page - it contains rather little information, and said information could be directly presented in the notice itself..

but I would like to continue with my goal and document the old & ugly modules in Phobos

I suggest to only keep what you need right now to do the above task, i.e. drop the compatibility index and stable macro, and just leave the macros for the notices to be used in Phobos.

Notice texts could be:

• Warning: This module is deprecated and will be removed on $1. Use $2 instead.

• Warning: This module is obsolete and may be removed in the future. $0

• Warning: This module is experimental and may be moved, changed, or removed in the future. $0

[CyberShadow]

BTW, intuitively "obsolete" seems like a stronger term than "deprecated", without prior knowledge I would guess that a module would go stable -> deprecated -> obsolete. I can't think of a better term though.

[andralex]

In C++ "deprecated" (e.g. exception specifications) is stronger than "obsolete" (e.g.strstream).

Interestingly http://m-w.com does not list the computer engineering meaning of "deprecated". However, it does suggest that "deprecated" is stronger than "obsolete":

https://www.merriam-webster.com/dictionary/deprecated
https://www.merriam-webster.com/dictionary/obsolete

The thesaurus may provide insight into possible alternative terms:

https://www.merriam-webster.com/thesaurus/deprecated
https://www.merriam-webster.com/thesaurus/obsolete

[andralex]

The obsolescence text should be:

Warning: This module is obsolete and may be superseded in the future. $0

[andralex]

In fact the way I see it something is obsolete if and only if it already has a better alternative.

[wilzbach]

Hmm, maybe before we proceed, let's better have a look on how we would apply and use these messages on Phobos.
Here's my list of OBSOLETE and DEPRECATED stuff.

• std.container: OBSOLETE (There are the faster, @nogc emsi-containers and work is in progress for a Phobos replacement)
• std.json: DEPRECATED -> std.data.json
• std.net.curl: OBSOLETE -> requests
• std.outbuffer: DEPRECATED -> std.conv + std.array.appender + the entire concept of output ranges needs to be reworked
• std.signals: DEPRECATED, e.g. phobosx:

Replacement for std.signals, with more features and less bugs.

or observe etc.

• std.stdint: DEPRECATED -> core.stdc.stdint
• std.socket: most likely we need to create a new module without classes if we want Sockets to be @nogc. Of course Vibe.d does a pretty job in regards of async connections, e.g. TCPConnection.
• std.uri: OBSOLETE -> alphaPhobos, vibe.inet.url, http2.d
• std.variant: OBSOLETE -> taggedalgebraic
• std.xml: OBSOLETE -> experimental.xml

Other ugly modules:

• std.base64 (combine with std.base32)
• std.encoding is really messy and semantically should contain std.utf

[andralex]

I think we'd be hasty.

• OBSOLETE: a better alternative exists in the standard library.
• DEPRECATED: a better alternative exists in the standard library, and the deprecated things will be removed on a precise schedule

We do NOT mark stuff as obsolete because there are alternatives outside the standard library.

[CyberShadow]

There are the faster, @nogc emsi-containers

Is that project still alive? I sent a PR last year and it's still open. Last commit was also last year.

[andralex]

I now realize how my previous comment might have been misunderstood - I assumed "within the standard library" is implied.

[JackStouffer]

Is that project still alive? I sent a PR last year and it's still open. Last commit was also last year.

IIRC EMSI uses the library internally, so it's probably not "dead".

[CyberShadow]

Hmm, I guess it's not really relevant here any more but I guess a library may still be used whereas its open source project might be dead, due to dwindling interest of reviewing outside contributions or conflicts of interest.

[MartinNowak]

In fact the way I see it something is obsolete if and only if it already has a better alternative.

That's a strong requirement, hardly anyone want's to introduce a replacement for std.signal.

We do NOT mark stuff as obsolete because there are alternatives outside the standard library.

If there was a much better alternative and everyone in the community knew to use fastxml instead of std.xml, is it really a good idea not to mention that?

The way you said it makes it sound like a strict rule, while a bit of leeway might be more appropriate.

[MartinNowak]

This discussion suggests that there is not much difference between obsolete and deprecated.
https://english.stackexchange.com/questions/87887/what-is-the-difference-between-obsolete-and-deprecate-in-computer-science
We want something as simple as For new code it is recommended to use XYZ instead., maybe we don't even need to find/invent the right adjective for that.
If we still want one I'd rather use outdated or superseded than obsolete.

[andralex]

I definitely agree with some flexibility.

If std.signal is rendered essentially useless by simple use of language features and idioms, yes let's mark it as obsolete/deprecate/yank.

Faster/better alternatives to standard artifacts exist in probably most languages, and for most artifacts. But it's uncommon to throw away the standard implementation on account of that - even for the most egregious cases such as C++ iostreams, which must count as the worst I/O library in the history of humankind.

[andralex]

Love Superseded by: $0. We could even make it a standard ddoc tag.

[wilzbach]

Alrighty - I rebased this PR to a general concept of a MESSAGE_BOX, s.t. defining a deprecation is as easy as:

COMPATIBILITY_BOX_DEPRECATED = $(MESSAGE_BOX red, $(B Deprecated) - $0)

I added a few predefined ones, but we could also remove all of them, and just add MESSAGE_BOX.
And with MESSAGE_BOX start adding warnings to Phobos and once we have agreed and realized which definitions are necessary, standardize and re-add them.

[CyberShadow]

Merging, as it's now just a few macro definitions and CSS rules.