www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Deprecation process documented?

reply Jacob Carlborg <doob me.com> writes:
Is the deprecation process used for Phobos and druntime code documented 
somewhere? I.e. how long after a deprecation is a symbols removed and so on.

-- 
/Jacob Carlborg
Feb 23 2015
next sibling parent reply Jonathan M Davis via Digitalmars-d-learn writes:
On Tuesday, February 24, 2015 08:49:55 Jacob Carlborg via Digitalmars-d-learn
wrote:

 Is the deprecation process used for Phobos and druntime code documented
 somewhere? I.e. how long after a deprecation is a symbols removed and so on.


No, it's not documented. I really should put it up on the wiki. The current
process is that if the replacement for the symbol is being introduced at the
same time, the old symbol will be marked as deprecated for a release (so
that it's possible for code to build on both the latest release and on
master without getting deprecation messages with either). If there is no
replacement, or the replacement already exists, then that's not necessary.
After that, the symbol is deprecated but documented for about a year. Then
it's undocumented but remains there and deprecated for about another year,
and then it finally gets removed entirely.

Release dates tend to screw with how consistent the timing is (since the
release dates generally haven't been consistent or even necessarily
frequent), and sometimes we adjust it depending on the particular
circumstances of a symbol. And of course, we've been trying to deprecate
stuff rarely for a while now, so there isn't much going through the
deprecation process at the moment. But that's approximately what we've been
doing with the deprecation process for a while now.

If anything sits in a particular stage of the deprecation cycle for longer
than that, it's typically either because I didn't get around to moving it
along when I was supposed to or because someone else deprecated it and
didn't mark it the way that I normally mark them, in which case, I sometimes
miss those.

- Jonathan M Davis
Feb 24 2015
parent reply Jacob Carlborg <doob me.com> writes:
On 2015-02-24 10:20, Jonathan M Davis via Digitalmars-d-learn wrote:


 No, it's not documented. I really should put it up on the wiki. The current
 process is that if the replacement for the symbol is being introduced at the
 same time, the old symbol will be marked as deprecated for a release (so
 that it's possible for code to build on both the latest release and on
 master without getting deprecation messages with either). If there is no
 replacement, or the replacement already exists, then that's not necessary.
 After that, the symbol is deprecated but documented for about a year. Then
 it's undocumented but remains there and deprecated for about another year,
 and then it finally gets removed entirely.


Is the symbol deprecated right away or is there some kind of "scheduled 
for deprecation <date>" in the documentation?


 Release dates tend to screw with how consistent the timing is (since the
 release dates generally haven't been consistent or even necessarily
 frequent), and sometimes we adjust it depending on the particular
 circumstances of a symbol. And of course, we've been trying to deprecate
 stuff rarely for a while now, so there isn't much going through the
 deprecation process at the moment. But that's approximately what we've been
 doing with the deprecation process for a while now.

 If anything sits in a particular stage of the deprecation cycle for longer
 than that, it's typically either because I didn't get around to moving it
 along when I was supposed to or because someone else deprecated it and
 didn't mark it the way that I normally mark them, in which case, I sometimes
 miss those.


Ok, thanks.

-- 
/Jacob Carlborg
Feb 24 2015
next sibling parent reply Jonathan M Davis via Digitalmars-d-learn writes:
On Tuesday, February 24, 2015 17:57:12 Jacob Carlborg via Digitalmars-d-learn
wrote:

 On 2015-02-24 10:20, Jonathan M Davis via Digitalmars-d-learn wrote:


 No, it's not documented. I really should put it up on the wiki. The current
 process is that if the replacement for the symbol is being introduced at the
 same time, the old symbol will be marked as deprecated for a release (so
 that it's possible for code to build on both the latest release and on
 master without getting deprecation messages with either). If there is no
 replacement, or the replacement already exists, then that's not necessary.
 After that, the symbol is deprecated but documented for about a year. Then
 it's undocumented but remains there and deprecated for about another year,
 and then it finally gets removed entirely.


 Is the symbol deprecated right away or is there some kind of "scheduled
 for deprecation <date>" in the documentation?


Normally, the symbol is deprecated right away, because using a deprecated
symbol just results in a message being printing, but if a new symbol is
being introduced to replace the deprecated one at the same time that the
old symbol is deprecated, then we'll mark it as "scheduled for deprecation"
in the docs so that a project has a way to be built with both the latest
release and master without getting an deprecation messages. Previously, we
hadn't been doing that, but it caused Vladmir some problems when a symbol
that he was using in dfeed (or some other similar project) was in a template
and ended up flooding his console with deprecation messages, and he needed
to be able to build with both the latest release and with master. So, the
process was adjusted to take that into account.

Regardless, when a symbol is either marked as "scheduled for deprecation" in
the docs or outright deprecated, a date is usually put in the docs for when
it will be moved to the next deprecation stage, though in the case of
"scheduled for deprecation," there's a decent chance that it'll be marked
with the next release number rather than a date, since the idea there is to
give folks a release of leeway so that they can avoid deprecation messages
when building with master rather than give them a particular period of time
to change their code before the symbol goes away, as is the case with
symbols that are actually deprecated.

- Jonathan M Davis
Feb 24 2015
parent Jacob Carlborg <doob me.com> writes:
On 2015-02-24 18:55, Jonathan M Davis via Digitalmars-d-learn wrote:


 Normally, the symbol is deprecated right away, because using a deprecated
 symbol just results in a message being printing, but if a new symbol is
 being introduced to replace the deprecated one at the same time that the
 old symbol is deprecated, then we'll mark it as "scheduled for deprecation"
 in the docs so that a project has a way to be built with both the latest
 release and master without getting an deprecation messages. Previously, we
 hadn't been doing that, but it caused Vladmir some problems when a symbol
 that he was using in dfeed (or some other similar project) was in a template
 and ended up flooding his console with deprecation messages, and he needed
 to be able to build with both the latest release and with master. So, the
 process was adjusted to take that into account.

 Regardless, when a symbol is either marked as "scheduled for deprecation" in
 the docs or outright deprecated, a date is usually put in the docs for when
 it will be moved to the next deprecation stage, though in the case of
 "scheduled for deprecation," there's a decent chance that it'll be marked
 with the next release number rather than a date, since the idea there is to
 give folks a release of leeway so that they can avoid deprecation messages
 when building with master rather than give them a particular period of time
 to change their code before the symbol goes away, as is the case with
 symbols that are actually deprecated.


Thank you for the explanation.

-- 
/Jacob Carlborg
Feb 25 2015
prev sibling parent "H. S. Teoh via Digitalmars-d-learn" <digitalmars-d-learn puremagic.com> writes:
On Tue, Feb 24, 2015 at 09:55:28AM -0800, Jonathan M Davis via
Digitalmars-d-learn wrote:
[...]

 Regardless, when a symbol is either marked as "scheduled for
 deprecation" in the docs or outright deprecated, a date is usually put
 in the docs for when it will be moved to the next deprecation stage,
 though in the case of "scheduled for deprecation," there's a decent
 chance that it'll be marked with the next release number rather than a
 date, since the idea there is to give folks a release of leeway so
 that they can avoid deprecation messages when building with master
 rather than give them a particular period of time to change their code
 before the symbol goes away, as is the case with symbols that are
 actually deprecated.


[...]

What about Walter's recent complaint that certain old symbols have gone
away and no upgrade path was presented to the user, just an inscrutible
error message? I thought the consensus from that discussion was to leave
deprecated symbols undocumented but still defined (even if it's just a
no-op stub with a deprecation message or static assert pointing the user
to the new symbol(s)).


T

-- 
Right now I'm having amnesia and deja vu at the same time. I think I've
forgotten this before.
Feb 24 2015
prev sibling next sibling parent "FrankLike" <1150015857 qq.com> writes:
On Tuesday, 24 February 2015 at 07:49:55 UTC, Jacob Carlborg 
wrote:

Can you help me about 'Concurrency in D'? Thank you.

http://forum.dlang.org/thread/dugsyhsswoovgywplmbo forum.dlang.org

Some people think rust is better ,but I think D is better.
But I don't know that how to use 'Concurrency in D',Can you help 
me ?
Thank you.
Feb 24 2015
prev sibling parent Jonathan M Davis via Digitalmars-d-learn writes:
On Tuesday, February 24, 2015 10:05:21 H. S. Teoh via Digitalmars-d-learn wrote:

 On Tue, Feb 24, 2015 at 09:55:28AM -0800, Jonathan M Davis via
Digitalmars-d-learn wrote:
 [...]

 Regardless, when a symbol is either marked as "scheduled for
 deprecation" in the docs or outright deprecated, a date is usually put
 in the docs for when it will be moved to the next deprecation stage,
 though in the case of "scheduled for deprecation," there's a decent
 chance that it'll be marked with the next release number rather than a
 date, since the idea there is to give folks a release of leeway so
 that they can avoid deprecation messages when building with master
 rather than give them a particular period of time to change their code
 before the symbol goes away, as is the case with symbols that are
 actually deprecated.


 [...]

 What about Walter's recent complaint that certain old symbols have gone
 away and no upgrade path was presented to the user, just an inscrutible
 error message? I thought the consensus from that discussion was to leave
 deprecated symbols undocumented but still defined (even if it's just a
 no-op stub with a deprecation message or static assert pointing the user
 to the new symbol(s)).


There was some discussion of that, though I don't know that a consensus was
reached. I don't remember all of the details of that discussion though.
However, I do tend to be very much in favor of _not_ leaving cruft around
like that long term, so that may color what I'm remembering. However, the
problem that Walter ran into was because he waited over two years before
updating his code, and trying an intermediate release of the compiler and
std lib would have taken care of the problem.

- Jonathan M Davis
Feb 24 2015