deprecation vs removal
Luke Plant
The Django deprecation timeline [1] is very inconsistent in its usage of
the terminology 'deprecated'. For example, the 1.5 section often says
"is deprecated" or "has been deprecated", when what they mean is "will
be removed", which is what the other sections generally tend to say.
Some in section 1.6 say a feature "will be deprecated".
Can we have a consistent policy on this terminology?
Miriam-Webster:
"deprecate: to express disapproval of"
So something is 'deprecated' as soon as we say we are going to remove it
- we are expressing disapproval, but allowing it to continue
temporarily. The confusing thing from Python terminology is that we then
add PendingDeprecationWarning, followed by DeprecationWarning, which
suggest that deprecation is something that will happen in the *future*,
the thing that happens when we finally remove it. But that isn't normal
English usage, and we can't sensibly use 'deprecated' for both the
beginning and the end of the process.
So I'd suggest that we stick to:
- deprecated = the first time we say we are going to remove it,
and normally means we add PendingDeprecationWarning
- removed - when we actually remove.
In the deprecation timeline, we can simply say "X will be removed", or
"X will be removed in favour of Y". If it is outside the normal
deprecation policy in some way, we can mention that, otherwise no need
to say which version it was deprecated in. In our release notes, we
carry on announcing deprecation as we are doing now. The only problem is
that our 'deprecation timeline' effectively becomes a 'removal
timeline', but I think it will be clear enough if the rest of our
terminology is.
Comments?
Luke
[1] https://docs.djangoproject.com/en/dev/internals/deprecation/
--
"It is a truth universally acknowledged, that a single man in
possession of a good fortune, must be in want of a wife." (Jane
Austen)
Luke Plant || http://lukeplant.me.uk/
Paul McMillan
terminology is likely to confuse people for a while.
PendingDeprecation is a rather unfortunate construction. If we can
pull through the phase where people are confused, our terminology will
be more precise for the change. +1 from me.
Alexander Schepanovski
somewhat useless and confusing. I'd prefer deprecated elements were
just removed. Then when I upgrade django I'll just upgrade it and fix
any wrong calls, imports, monkey patches etc. Proper upgrading docs,
which you write anyway, will make it into a couple of days. The way it
is done now still requires that two days but also make me think about
separate deprecation concept, about what part of django is public and
what is not cause they have separate deprecation policies. It also
encourages me to slack at upgrading and use something deprecated for a
while longer.
Paul McMillan
> encourages me to slack at upgrading and use something deprecated for a
> while longer.
Yes, but in the meantime you're using the newer, better supported, and
often more-secure code. It allows you the luxury of taking the time,
and encourages you to upgrade even if you don't have time to make
application changes. This stability is an important promise for many
of our users.
Alexander Schepanovski
> and encourages you to upgrade even if you don't have time to make
> application changes.
Some of things I do with django are pretty tied up to its internals.
But even a common user, who himself doesn't hack into django may use
third-party libs that do: migration, automatic caching, any orm, form
and template extenders. And for the developers of that libs
deprecation is a waste not help, at least what it feels for me. For
common user this means he cannot upgrade until all hos libs upgraded
or he himself is forced into hacking them.
So dropping deprecation could be a strategic win in a sense it will
help django infrastructure flourish. At least this is worth
considering.
Ryan McIntosh
If you're being nagged by deprecation warnings than... well... That's the point!
The annotation "Will be deprecated" is also useful.
Change requires care, IMHO.
Many hackers on this list continually work on the latest version. Many don't.
peace,
Ryan McIntosh
Software Architect
PeaceWorks Technology Solutions
ph: (204) 480-0314
cell: (204) 770-3682
ry...@peaceworks.ca
--
You received this message because you are subscribed to the Google Groups "Django developers" group.
To post to this group, send email to django-d...@googlegroups.com.
To unsubscribe from this group, send email to django-develop...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.
Łukasz Rekucki
upgrade django I'll just upgrade it and fix> any wrong calls, imports,
monkey patches etc. Proper upgrading docs,> which you write anyway,
will make it into a couple of days. The way it> is done now still
requires that two days but also make me think about> separate
not cause they have separate deprecation policies. It also> encourages
me to sl
deprecated functions pop-up. The best part is that *I* choose when to
spend time on getting rid of them and I don't have to do it all at
once. I do this even with my own codebase.
On 2 October 2011 07:48, Alexander Schepanovski <suor...@gmail.com> wrote:
> But even a common user, who himself doesn't hack into django may use
> third-party libs that do: migration, automatic caching, any orm, form
> and template extenders. And for the developers of that libs
> deprecation is a waste not help, at least what it feels for me. For
> common user this means he cannot upgrade until all hos libs upgraded
> or he himself is forced into hacking them.
>
IMHO, it's exactly the opposite. If you remove the code right away,
then I can't upgrade to the new version of Django, 'cause I have to
wait for my 30 dependencies to upgrade or hack it my own.
---
As for the naming, it's probably because i'm not a native speaker, but
I always found the warning names logical. "PendingDeprecationWarning"
warns you about something, that will be deprecated in the version.
"DeprecationWarning" warns you that something *is* deprecated (as in
old and useless), so it *may* be removed in any future version.
Whether it is actually removed is another thing - Python itself has a
long tradition of leaving some C API functions deprecated for
indefinite period of time. So, to me, deprecation is the state right
before removal. I would stay with "X will be deprecated in Django Y.Z"
wording (which implies it may be removed in any (Y+m).(Z+1+n) n,m>=0
version).
--
Łukasz Rekucki
Stephen Burrows
phrases being discussed here. Sure, it's jargon. It might be more
accessible if we used other language. I don't really care one way or
the other. But it's jargon. The fact that Miriam-Webster doesn't know
what the word actually means doesn't prove that we're using it wrong.
Mainstream dictionaries often don't include technical jargon.
See also:
- http://en.wiktionary.org/wiki/deprecate :: (computing) To declare
something obsolescent, i.e., to recommend against a function,
technique, command, etc, that still works but has been replaced.
- en.wikipedia.org/wiki/Deprecate
Best,
Stephen Burrows
On Oct 2, 2:07 am, Łukasz Rekucki <lreku...@gmail.com> wrote:
> 2011/10/2 Alexander Schepanovski <suor....@gmail.com>:> Then when I
> monkey patches etc. Proper upgrading docs,> which you write anyway,
> will make it into a couple of days. The way it> is done now still
> requires that two days but also make me think about> separate
> deprecation concept, about what part of django is public and> what is
> not cause they have separate deprecation policies. It also> encourages
> me to sl
> I prefer to just run my test suite with warnings enabled and see where
> deprecated functions pop-up. The best part is that *I* choose when to
> spend time on getting rid of them and I don't have to do it all at
> once. I do this even with my own codebase.
>
Russell Keith-Magee
+1. I agree with Paul that "PendingDeprecationWarning" is slightly
problematic from a language perspective because we're saying that
we're deprecating a feature now, and implementing that by raising a
Pending warning. However, I think that's a mild inconsistency I can
live with.
Yours,
Russ Magee %-)
ptone
On Oct 1, 9:10 am, Luke Plant <L.Plant...@cantab.net> wrote:
> Hi all,
>
> The Django deprecation timeline [1] is very inconsistent in its usage of
> the terminology 'deprecated'. For example, the 1.5 section often says
> "is deprecated" or "has been deprecated", when what they mean is "will
> be removed", which is what the other sections generally tend to say.
> Some in section 1.6 say a feature "will be deprecated".
policy for each item.
Not all deprecations are removals, some are API changes.
I still think that the doc is basically forward looking, so future
tense should be preserved - I don't think any mention of when the item
was first deprecated is needed (as I said, that is in the policy and
does not need to be repeated). I do think links to sections of
release notes are useful instead of restating the reasons in full.
On Oct 3, 6:35 am, Russell Keith-Magee <russ...@keith-magee.com>
wrote:
> problematic from a language perspective because we're saying that
> we're deprecating a feature now, and implementing that by raising a
> Pending warning. However, I think that's a mild inconsistency I can
> live with.
given that the policy is a relatively generous 2 version path, I like
that PendingDeprecationWarning allows a sort of "soft deprecation".
That is, if there was a large change in opinion (low probability), the
deprecation could be reverted. Other's may object to this, but I
think adopting sort of a deprecation "beta" would allow for some
slightly more aggressive deprecation, with a period for community
feedback. Many people will read release notes who don't pay attention
to deprecation discussions in dev. The big downside to formalizing
this is that the decision could appear wishy-washy, or could be
subject to vocal minority crusades against a deprecation, so I'm +0
about it ;-)
-Preston
Russell Keith-Magee
I'm completely agreed that the 'soft' deprecation is useful. I'm just
complaining about the ambiguity in the language: "We're deprecating
this feature by marking it PendingDeprecation...".
Yours,
Russ Magee %-)
Joe & Anne Tennies
It sounds like there's generally agreement that people need to be warned that something is going to be removed. It sounds like people that maintain code that is required to be stable and relies on other people's code needs a "this is going to be removed" and a "now I really mean it this time".
Django currently has a system that accomplishes this and that is well documented. This leaves the actual term as the problem. The current terms used are common enough to make http://www.webopedia.com/TERM/D/deprecated.html
I would rather see the effort on something that Django currently does not do as well as it needs to and not something it does well and is well understood.
Russell Keith-Magee
> I know that no one knows who I am, but I'm going to say that this is
> becoming a bike shed.
There appears to be some confusion here -- nobody is proposing
changing *anything* about Django's deprecation policy. All we are
doing is attempting to get some consistency in the *language* that we
use, especially in the deprecation guide document [1]. If you read the
current document, the language used varies wildly -- see Luke's
original email for a full list of the problems). In the interests of
clarity, Luke has proposed normalizing the language, and so far, I
haven't seen any disagreement that the language cleanup he has
proposed is the right thing to do. All I've noted is that there is an
unfortunate inconsistency in the naming of PendingDeprecation, but
there's not much we can do about that.
[1] https://docs.djangoproject.com/en/dev/internals/deprecation/
Yours,
Russ Magee %-)
Tai Lee
On Oct 4, 11:17 am, Russell Keith-Magee <russ...@keith-magee.com>
wrote:
> complaining about the ambiguity in the language: "We're deprecating
> this feature by marking it PendingDeprecation...".
"SoftDeprecation..." or "QuietDeprecation..."? It's not really pending
deprecation. It is deprecated already, but we just don't loudly
complain (yet) if people haven't updated their code immediately.
Cheers.
Tai.
Justin Holmes
> --
> You received this message because you are subscribed to the Google Groups "Django developers" group.
> To post to this group, send email to django-d...@googlegroups.com.
> To unsubscribe from this group, send email to django-develop...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.
>
>
--
Justin Holmes
Head Instructor, SlashRoot Collective
SlashRoot: Coffee House and Tech Dojo
60 Main Street
New Paltz, NY 12561
845.633.8330
Luke Plant
PendingDeprecationWarning and DeprecationWarning are Python builtins:
http://docs.python.org/library/exceptions.html
so we can't change the names unless we want to introduce our own
alternative, which would definitely be a bad idea IMO.
PendingDeprecation is already quiet by default.
Regards,
Luke
--
"I was sad because I had no shoes, until I met a man who had no
feet. So I said, "Got any shoes you're not using?" (Steven Wright)
Luke Plant || http://lukeplant.me.uk/
ptone
>
> The Django deprecation timeline [1] is very inconsistent in its usage of
> the terminology 'deprecated'. For example, the 1.5 section often says
> "is deprecated" or "has been deprecated", when what they mean is "will
> be removed", which is what the other sections generally tend to say.
> Some in section 1.6 say a feature "will be deprecated".
>
> Can we have a consistent policy on this terminology?
be more consistent in language - review would be welcome:
https://code.djangoproject.com/ticket/16988
https://github.com/django/django/pull/58
-Preston