Use of the @deprecated tag

[Chris Davenport]

It came to my attention a while back that our use of the version number in @deprecated tags is ambiguous.  Does the number mean the version when the deprecation notice was raised, or the version when the code will be removed?  PLT has now decided to interpret it as the former (see [1]).  For example, "@deprecated 3.6" means that during the development of 3.6 it was decided to deprecate the code it refers to.  According to our development strategy [2] this means that the code should be removed in 4.0.

There are currently a number of "@deprecated 4.0" tags in our codebase which are obviously not correct according to this interpretation.  Anyone like to volunteer to spend a bit of time creating a PR to correct them?  Reply here if you'd like to take it on.

Thanks in anticipation,

Chris.

[1] https://volunteers.joomla.org/leadership/production-leadership-team/reports/336-plt-meeting-september-29-2016
[2] https://developer.joomla.org/cms/development-strategy.html Section 6.2

--

Chris Davenport
Joomla Production Leadership Team

[Sergio Manzi]

If this may help, I very well remember that at least in one of my now merged 3.x PRs I was instructed by maintainers to put an "@deprecated 4.0" meaning that it would be removed (or not guaranteed to be there) when 4.0 will be released.

I can't exactly remember in which PR(s) that was, but if needed I think I can find it out.

Sergio

--
You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cm...@googlegroups.com.
To post to this group, send email to joomla-...@googlegroups.com.
Visit this group at https://groups.google.com/group/joomla-dev-cms.
For more options, visit https://groups.google.com/d/optout.

[Michael Babker]

Seems a little odd that a decision would be made that invalidates the mass majority of our doc blocks?  https://api.joomla.org/cms-3/deprecated.html

Personally, instead of changing the interpretation, given the majority of use cases indicating the version the referenced code is scheduled to be removed at, I'd suggest revising the documentation to clear up any ambiguity.  Otherwise we're now asking contributors to crawl through at least six years of commit history (JError being the oldest deprecated class if I'm not mistaken which has been deprecated since somewhere around 1.6 or 1.7) to revise these blocks.  And that only covers the CMS repo.

--

You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cms+unsubscribe@googlegroups.com.
To post to this group, send email to joomla-dev-cms@googlegroups.com.

Visit this group at https://groups.google.com/group/joomla-dev-cms.
For more options, visit https://groups.google.com/d/optout.

--
- Michael

Please pardon any errors, this message was sent from my iPhone.

[Sergio Manzi]

... but I agree that it would make sense to adopt the new meaning, i.e. putting deprecation notice for the version "since when" something is considered obsolete and hence will be removed at the next major.

Only problem I foresee is that when one push a PR, he/she'll never can be sure if/when it will be merged.

This said, I think we should deprecate the old meaning @4.0 and start over from there.

Sergio

To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cm...@googlegroups.com.
To post to this group, send email to joomla-...@googlegroups.com.

[Niels Braczek]

Am 30.09.2016 um 01:29 schrieb Chris Davenport:

> It came to my attention a while back that our use of the version number in
> @deprecated tags is ambiguous. Does the number mean the version when the
> deprecation notice was raised, or the version when the code will be
> removed?

The defined meaning of the version in the the @deprecated tag is
(according to
https://phpdoc.org/docs/latest/references/phpdoc/tags/deprecated.html):

"This tag MAY also contain a version number up till which it is
guaranteed to be included in the software. Starting with the given
version, the function will be removed or may be removed without further
notice."

So I don't see any choice here. Everybody looking at the code will
expect the tag following the definition above.

Regards,
Niels

--
| New Stars on the Horizon: GreenCape · nibralab · laJoom |
| http://www.bsds.de · BSDS Braczek Software- und DatenSysteme |
| Webdesign · Webhosting · e-Commerce · Joomla! Content Management |
------------------------------------------------------------------

[Sergio Manzi]

You are right! I stand corrected.

Sergio

[Izhar Aazmi]

When something is deprecated we are more often than not, not certain about when the code will be removed, however there has been a kind of anticipation as well as major/minor release protocol involved deciding it so far. Not guaranteed though.

Therefore, I'd suggest keeping both values in the deprecation tags, so that one can always say when something was deprecated and until when it is still safe to use them. Maybe something like

@deprecated  3.6

@remove      4.0

or just as simple as indicating the period during which it will remain deprecated and removed (likely) thereafter.

@deprecated  3.6 – 4.0

And about the volunteering part, I will certainly try to participate in making those changes as much as possible. However honestly, being a developer my priorities would be bug fixes and improvements. I have few promises lined up already, and I'm already feeling sorry for not being able to put enough time :-/ to Joomla.

--

	Izharul Haque Aazmi (Izhar Aazmi)
	Bhartiy Digital Laboratories and Bhartiy Web Technologies, 11 - Kaveri Enclave - II, Near Swarn Jayanti Nagar, Ramghat Road, Aligarh - 202 001 (UP), India
	Visit: www.izharaazmi.com

--

[Chris Davenport]

@Niels. I agree that the phpDocumentor should be definitive, and that was something that we took into consideration, however, it appears to have been frequently misinterpreted both within this project and across others.  So much so that the "in the wild" interpretation would have to be considered ambiguous.

More recently, the upcoming PSR-5, which until recently was being led by Mike van Riel, the developer of phpDocumentor, suggests interpreting the version number as the "starting version", that is, the version in which the deprecation was first raised.

@Izhar. Yes, having both numbers is a good idea since it removes the ambiguity entirely.  To that end, I would suggest we adopt the PSR 5 definition even though PSR 5 is still only a draft.  See https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#75-deprecated

Going forward, you can add @deprecated __DEPLOY_VERSION__ or @deprecated __DEPLOY_VERSION__:4.0 and the build script will automatically insert the starting version number.

Chris.

To post to this group, send email to joomla-...@googlegroups.com.

Visit this group at https://groups.google.com/group/joomla-dev-cms.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cms+unsubscribe@googlegroups.com.
To post to this group, send email to joomla-dev-cms@googlegroups.com.

Visit this group at https://groups.google.com/group/joomla-dev-cms.
For more options, visit https://groups.google.com/d/optout.

[Niels Braczek]

Am 30.09.2016 um 10:05 schrieb Chris Davenport:

> Going forward, you can add @deprecated __DEPLOY_VERSION__ or @deprecated
> __DEPLOY_VERSION__:4.0 and the build script will automatically insert the
> starting version number.

I'm all in for adopting PSR-5.

[Michael Babker]

Can we make a policy to just use the starting version number?  Otherwise the colon annotation is going to be very easily more confusing than the perceived confusion of the existing "@deprecated 4.0" annotations (who actually uses the colon ending version format anyway!?).

@deprecated  3.6.3

@deprecated  3.6.3:4.0

Is there a team organizing to go through the project's repositories (I'm assuming this policy applies to all Joomla code and we are not yet again creating a CMS specific rule) to correct all annotations to match this decision, since as I pointed out previously the vast majority of existing annotations do not use the new recommendation?

--
You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cms+unsubscribe@googlegroups.com.

To post to this group, send an email to joomla-dev-cms@googlegroups.com.

[brian teeman]

Do you have some examples of where it has been misused. All the notices I have seen are clear that they mean the item is deprecated now and should be removed in the version stated.

[Michael Babker]

https://api.joomla.org/cms-3/deprecated.html

Everything on that page using a 3.x version number.  Unfortunately that's only covering the libraries folder so there may be more in the extensions.

On Fri, Sep 30, 2016 at 1:58 PM, 'brian teeman' via Joomla! CMS Development <joomla-...@googlegroups.com> wrote:

Do you have some examples of where it has been misused. All the notices I have seen are clear that they mean the item is deprecated now and should be removed in the version stated.

[brian teeman]

On Friday, 30 September 2016 00:30:01 UTC+1, Chris Davenport wrote:

There are currently a number of "@deprecated 4.0" tags in our codebase which are obviously not correct according to this interpretation.  Anyone like to volunteer to spend a bit of time creating a PR to correct them?  Reply here if you'd like to take it on.

If you mean that you want all @deprecated 4.0 to be changed to @deprecated 3.7 I can do that. Its not realistic to go back and work out exactly which version all the tags were added

[brian teeman]

https://github.com/joomla/joomla-cms/pull/12241 

[Chris Davenport]

If it involves too much work to fix the current codebase (properly), then maybe we can make a clean break in 4.0 and switch to the PSR5 (almost) standard with the full range syntax.  That way it will be clear going forwards and only slightly ambiguous looking backwards as well as not requiring any effort from anyone.

Chris.

--

You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cms+unsubscribe@googlegroups.com.

To post to this group, send email to joomla-dev-cms@googlegroups.com.

Visit this group at https://groups.google.com/group/joomla-dev-cms.
For more options, visit https://groups.google.com/d/optout.

[brian teeman]

On Saturday, 1 October 2016 16:44:13 UTC+1, Chris Davenport wrote:

If it involves too much work to fix the current codebase (properly), then maybe we can make a clean break in 4.0 and switch to the PSR5 (almost) standard with the full range syntax.  That way it will be clear going forwards and only slightly ambiguous looking backwards as well as not requiring any effort from anyone.

No idea at all what you mean by "properly" 

What is wrong with the PR that I did? 

Any reason not to just say thank you

 

Chris.

On 1 October 2016 at 15:26, 'brian teeman' via Joomla! CMS Development <joomla-...@googlegroups.com> wrote:

On Saturday, 1 October 2016 09:50:48 UTC+1, brian teeman wrote:

On Friday, 30 September 2016 00:30:01 UTC+1, Chris Davenport wrote:

There are currently a number of "@deprecated 4.0" tags in our codebase which are obviously not correct according to this interpretation.  Anyone like to volunteer to spend a bit of time creating a PR to correct them?  Reply here if you'd like to take it on.

If you mean that you want all @deprecated 4.0 to be changed to @deprecated 3.7 I can do that. Its not realistic to go back and work out exactly which version all the tags were added

https://github.com/joomla/joomla-cms/pull/12241 

--
You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cm...@googlegroups.com.
To post to this group, send email to joomla-...@googlegroups.com.

Visit this group at https://groups.google.com/group/joomla-dev-cms.
For more options, visit https://groups.google.com/d/optout.

[Chris Davenport]

By "properly" I meant going back through the logs to find the correct deprecation versions.  It looks to be a bigger job than I anticipated.  But, of course, thank you for your PR.  I really do appreciate the work you do.  What do you think of my compromise proposal?

Chris.

To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cms+unsubscribe@googlegroups.com.
To post to this group, send email to joomla-dev-cms@googlegroups.com.

Visit this group at https://groups.google.com/group/joomla-dev-cms.
For more options, visit https://groups.google.com/d/optout.

[brian teeman]

That's the problem when you make a decision and take a vote in something without considering the facts of the issue.

Closing my pr

[Izhar Aazmi]

@chris I understand that the work and effort for doing it "properly" is huge.

Work by Brian is a good workaround. We cannot expect him to do more than that, else it would be underutilization of his skill level.

However on a second thought, I find it misleading to mark everything deprecated in 3.7. Can't we rather choose some way that allows us to atleast mark them as deprecated before 3.7, such as 3.x (not exactly).
And mark deprecated 3.7 only those things that are actually deprecated in particularly 3.7.

Do we have a choice, Chris... Brian...?

I can also find some trainees to do it "properly" if you guys still think we should think of it.

On 2 Oct 2016 2:20 a.m., "Chris Davenport" <chris.d...@joomla.org> wrote:

By "properly" I meant going back through the logs to find the correct deprecation versions.  It looks to be a bigger job than I anticipated.  But, of course, thank you for your PR.  I really do appreciate the work you do.  What do you think of my compromise proposal?

Chris.

[Hannes Papenberg]

Let me make a bold proposal: Reconsider that decision and simply leave
it as is, using the phpdocumentor meaning that the version number is the
version where it is not going to be available anymore.

Hannes

Am 01.10.2016 um 23:31 schrieb Izhar Aazmi:
> @chris I understand that the work and effort for doing it "properly" is
> huge.
>
> Work by Brian is a good workaround. We cannot expect him to do more than
> that, else it would be underutilization of his skill level.
>
> However on a second thought, I find it misleading to mark everything
> deprecated in 3.7. Can't we rather choose some way that allows us to
> atleast mark them as deprecated before 3.7, such as 3.x (not exactly).
> And mark deprecated 3.7 only those things that are actually deprecated
> in particularly 3.7.
>
> Do we have a choice, Chris... Brian...?
>
> I can also find some trainees to do it "properly" if you guys still
> think we should think of it.
>
>
> On 2 Oct 2016 2:20 a.m., "Chris Davenport" <chris.d...@joomla.org

> <mailto:chris.d...@joomla.org>> wrote:
>
> By "properly" I meant going back through the logs to find the
> correct deprecation versions. It looks to be a bigger job than I
> anticipated. But, of course, thank you for your PR. I really do
> appreciate the work you do. What do you think of my compromise
> proposal?
>
> Chris.
>
> On 1 October 2016 at 17:29, 'brian teeman' via Joomla! CMS

> Development <joomla-...@googlegroups.com

> <https://groups.google.com/group/joomla-dev-cms>.

> For more options, visit
> https://groups.google.com/d/optout

> <https://groups.google.com/d/optout>.

>
>
>
>
> --
> Chris Davenport
> Joomla Production Leadership Team
>
> --
> You received this message because you are subscribed to the
> Google Groups "Joomla! CMS Development" group.
> To unsubscribe from this group and stop receiving emails from

> it, send an email to joomla-dev-cm...@googlegroups.com
> <mailto:joomla-dev-cm...@googlegroups.com>.

> To post to this group, send email to
> joomla-...@googlegroups.com

> <mailto:joomla-...@googlegroups.com>.

> Visit this group at
> https://groups.google.com/group/joomla-dev-cms

> <https://groups.google.com/group/joomla-dev-cms>.

> For more options, visit https://groups.google.com/d/optout

> <https://groups.google.com/d/optout>.

>
>
>
>
> --
> Chris Davenport
> Joomla Production Leadership Team
>
> --
> You received this message because you are subscribed to the Google
> Groups "Joomla! CMS Development" group.
> To unsubscribe from this group and stop receiving emails from it,

> send an email to joomla-dev-cm...@googlegroups.com
> <mailto:joomla-dev-cm...@googlegroups.com>.

> To post to this group, send email to joomla-...@googlegroups.com

> <mailto:joomla-...@googlegroups.com>.

> Visit this group at https://groups.google.com/group/joomla-dev-cms

> <https://groups.google.com/group/joomla-dev-cms>.

> For more options, visit https://groups.google.com/d/optout

> <https://groups.google.com/d/optout>.

>
>
> --
> You received this message because you are subscribed to the Google
> Groups "Joomla! CMS Development" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to joomla-dev-cm...@googlegroups.com

> <mailto:joomla-dev-cm...@googlegroups.com>.

> To post to this group, send email to joomla-...@googlegroups.com

> <mailto:joomla-...@googlegroups.com>.

[Walt Sorensen aka photodude]

From the PSR-5 suggestion "The 'starting version' MAY be omitted. In this case, the 'ending version' MUST be preceded by a colon."

Seems reasonable to assume our existing @deprecated  4.0 could easily be changed to @deprecated  :4.0

Personally, I don't like the colon notation at all as I think it's too easy to misread and too easy for people to at a glance to misunderstand. I would prefer a hyphen notation for a single line as in 

@deprecated  3.6.3-4.0
or following the omission of the starting version; the 'ending version' MUST be preceded by a hyphen
@deprecated  -4.0

(note: I'm not sure I'm in love with the idea of a hyphen notation for a single line @deprecated, but it's an improvement over the colon notation)

[Webdongle Elgnodbew]

From a users point of view
'Deprecated 4.0' = that the code still works with version 4.0 but is not to be included in extensions written for version 4.0. because it will be 'Obsolete' soon.
'Obsolete 5.0' = that the code does not work in version 5.0 and was previously deprecated

In other words to have more than one version with the word 'Deprecated' (or to have one version with a hyphen/colon/semi-colon) is misleading and incorrect.

On Friday, 30 September 2016 00:30:01 UTC+1, Chris Davenport wrote:

[Michael Babker]

Obsolete isn't a standard annotation anywhere, and IMO that doesn't communicate things well at all.

Previously, for the most part, the annotations "@deprecated  4.0" indicated that the documented object is deprecated and should no longer be used and would be removed at the earliest at 4.0.

What the proposal now does (assuming I'm following this right because it is becoming as clear as mud the longer this thread goes on) is that one of the following three notations is acceptable:

@deprecated  3.6.3 to indicate that the method has been deprecated since 3.6.3 and may be removed at the earliest at the next major version increment

@deprecated  3.6.3:4.0 to indicate that the method has been deprecated since 3.6.3 and may be removed at the earliest at version 4.0

@deprecated  :4.0 to indicate the method has been deprecated (no "since" version) and may be removed at the earliest at 4.0 (this is closest to the majority use in the code today)

TBH, the PSR-5 suggestion on this annotation is even more crap than the supposed ambiguity with the existing use.  If you want to change the standard and remove all ambiguity, follow Symfony's code.  http://api.symfony.com/2.7/Symfony/Component/Security/Core/SecurityContext.html

--

You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cms+unsubscribe@googlegroups.com.
To post to this group, send email to joomla-dev-cms@googlegroups.com.

[Hannes Papenberg]

Please keep in mind that a deprecation notice would have to be added in
a minor version release (not a patch release) and thus @deprecated means
"Don't use this, because it is going to go away in the next major
release, BUT you will get 2 more years of support out of this." I don't
see how another notation like "obsolete" would help here.

Hannes

> --
> You received this message because you are subscribed to the Google
> Groups "Joomla! CMS Development" group.
> To unsubscribe from this group and stop receiving emails from it, send

> an email to joomla-dev-cm...@googlegroups.com
> <mailto:joomla-dev-cm...@googlegroups.com>.
> To post to this group, send email to joomla-...@googlegroups.com
> <mailto:joomla-...@googlegroups.com>.

[Jacques Rentzke]

Use more words in the tag, if the short version is ambiguous or causes confusion:

Example: 

For code that is scheduled for removal in a future release:

@deprecated for removal in 4.0

or if it is not sure when exactly the code will be removed in future:

@deprecated since 3.4.0

and if you want to be really thorough:

@deprecated since 3.4.0 for removal in 4.0

Jacques

[Webdongle Elgnodbew]

@deprecated  3.6.3

Understandable

 @deprecated  3.6.3:4.0

 @deprecated  :4.0

Totally confusing

 
@ Jacques Rentzke
Yes, would be better

To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cm...@googlegroups.com.
To post to this group, send email to joomla-...@googlegroups.com.

[brian teeman]

Don't forget these messages are intended for developers not users!

[Webdongle Elgnodbew]

Thanks Brian good point.  However many users (while not trained developers) do create Template's and Template overrides.  Also there are users who have problems with 3rd party Template overrides and edit them.  Does the deprecated code not apply to overrides ?   

[Niels Braczek]

Am 03.10.2016 um 16:10 schrieb 'brian teeman' via Joomla! CMS Development:

> Don't forget these messages are intended for developers not users!

... *and* should be machine-readable for automatic processing.

[Jacques Rentzke]

Yes, it is meant for developers, but it is these same developers who are at the moment confused about how Joomla uses @deprecated.

And it can be solved by being more descriptive, instead of using symbols that mean different things to different developers/projects.

That's my suggestion.

Jacques

[Michael Babker]

I'm still confused where the confusion lies.  Until this thread I honestly can't remember any discussions around the tag's meaning (not saying the confusion doesn't exist but at best it seems to have lied with very few people).  What was so confusing about "@deprecated  4.0" beyond it wasn't used consistently (seen in the code by the fact some annotations use the version they were deprecated at versus the version they'd be removed) or the fact that the tag isn't a complete sentence like Symfony's code standard?

--

You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cms+unsubscribe@googlegroups.com.
To post to this group, send email to joomla-dev-cms@googlegroups.com.

[Walt Sorensen aka photodude]

Here is a non-exhaustive list of possible options; I'm open to any options that have more visual significance than the current proposed single-colon notation.

Alternative	Char(s)	example1	example2
Double colon	::	@deprecated 1.0.0::2.0.0	@deprecated ::2.0.0
Forward slash	/	@deprecated 1.0.0/2.0.0	@deprecated /2.0.0
Double Forward slash	//	@deprecated 1.0.0//2.0.0	@deprecated //2.0.0
Backslash	\	@deprecated 1.0.0\2.0.0	@deprecated \2.0.0
Double Backslash	\\	@deprecated 1.0.0\\2.0.0	@deprecated \\2.0.0
Pointer	->	@deprecated 1.0.0->2.0.0	@deprecated ->2.0.0
Tilde	~	@deprecated 1.0.0~2.0.0	@deprecated ~2.0.0
Hyphen	-	@deprecated 1.0.0-2.0.0	@deprecated -2.0.0
Underscore	_	@deprecated 1.0.0_2.0.0	@deprecated _2.0.0
verbose words	since #.#.# for removal in #.#.#	@deprecated since 1.0.0 for removal in 2.0.0	@deprecated for removal in 2.0.0

A complete sentence like Symfony's code standard is going to have the least amount of confusion

[brian teeman]

Are you offering to go through thousands of PR to find the version that something was deprecated at. If not then this really is a mute argument. 

PLT made a decision based on a lack of information and without considering the consequences - as I dont see any of the PLT members coming up with any practical  suggestions or offering to do the work its time to file this under "interesting ideas not implemented"

[Walt Sorensen aka photodude]

Brian, I agree the PLT made a decision without fully considering the consequences or how it could waste development time. 

My comment should be taken with the understanding that "The 'starting version' MAY be omitted. In this case, the 'ending version' MUST be preceded by a __Fil in char that is agreed on__." and continue to assume that these were all "remove version" thus making a small adjustment as a search and replace.

However, I agree that it's probably "time to file this under "interesting ideas not implemented"". We should just put how we are using the @depreceated tag in the code style manual and move on.

[Chris Davenport]

I'll look again at this issue when I have more time.

Thanks for the feedback and discussion.

Chris.

--

You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cms+unsubscribe@googlegroups.com.
To post to this group, send email to joomla-dev-cms@googlegroups.com.
Visit this group at https://groups.google.com/group/joomla-dev-cms.
For more options, visit https://groups.google.com/d/optout.