Improvements to deprecations related to `since` parameter #5076

soc · 2016-04-02T11:41:39Z

No description provided.

soc · 2016-04-03T08:15:08Z

som-snytt · 2016-04-03T10:33:32Z

src/reflect/scala/reflect/internal/Symbols.scala

+    def deprecationMessage     = getAnnotation(DeprecatedAttr) flatMap (_ stringArg 0)
+    def deprecationVersion     = getAnnotation(DeprecatedAttr) flatMap (_ stringArg 1)
+    def deprecatedParamName    = getAnnotation(DeprecatedNameAttr) flatMap (_ symbolArg 0 orElse Some(nme.NO_NAME))
+    def deprecatedParamVersion = getAnnotation(DeprecatedNameAttr) flatMap (_ stringArg 1)


This longer name caused a big shift for column alignment, while subsequent long names are wrapped. Just eyeballing, it doesn't look determined by line length. Maybe avoid white space changes?

I kept the wrapping starting with the next "category" of methods, it didn't feel right to have deprecatedParamName unwrapped and deprecatedParamVersion wrapped. If I wrapped deprecatedParamName I would also have to start wrapping the same-length hasBridgeAnnotation above...

I would have wrapped deprecatedParamVersion; my eyes see a long block of stuff about deprecated stuff; I was only thinking of minimizing whitespace change so it's easier to see the real diff later. I don't know if github will ignore whitespace in diff views. Or maybe add vertical space if grouping is significant. Just a thought.

som-snytt · 2016-04-03T11:28:17Z

There is a JEP for improved deprecation in Java 9. I see it's linked on jira. They recently simplified, in order not to encode reasons and lifecycle disposition and replacement API that should be discussed in documentation. I can't tell if they eliminated "condemned" or renamed it "forRemoval"? But one point is that it doesn't give enough information, since projects have arbitrary lifecycles or policies for whether to remove deprecated API.

In a word, I'm not sure f has been deprecated (since 2.11) in an error message tells me more useful info. If there's more to be said about what deprecation means for this API, I should read the docs. Just because something has been deprecated since 2.9 doesn't mean it's scheduled for removal. That's certainly not the case for projects in general. So reporting it may be a job for a doc or lint tool.

Also, javac says "has been deprecated." For some reason it sounds more natural than "is deprecated." That may be because the verb is transitive or for sense of completion. "--What happened to the food? --The food has been eaten." Food in general is eaten because edible.

soc · 2016-04-03T12:02:48Z

The whole reason why since is a String was that projects can add their own project name in front of it.

I know the Java 9 JEP. The problem is that they are still living in a world where the only imaginable way of dealing with deprecations is their own. From an improvement point of view, I think that @deprecated{,Name,Overriding,Inheritance} is vastly better for developers than their semantic games of adding more nuance to their deprecation annotations. I'm pretty pretty sure they will revert back to "we never remove anything deprecated" after they managed to ship Jigsaw anyway.

"deprecated (since FooBarLib 33.2)" is meaningful, because developers can check what the project's deprecation policy is.

That's the idea behind it: Instead of giving people "13 deprecation warnings, and now deal with it" we provide them with some additional helpful information which helps them to determine how critical a deprecation is:

warning: there was one deprecation warning (since 2.11.0)
warning: there were two deprecation warnings (since 2.12.0)
warning: there were five deprecation warnings (since FooBarLib 33.2)
warning: there were two deprecation warnings (since FooBarLib 32.8)
warning: there were three deprecation warnings (since BazProject 12)
warning: there were 13 deprecation warnings in total; re-run with -deprecation for details

A Scala developer already knows the Scala deprecation policy, therefore he/she has to check only FooBarLib's and BazProject's policies, instead of checking every single deprecation manually.

"has been" -> "is" was just to offset the potential width increase from the since information.

som-snytt · 2016-04-03T12:12:55Z

I like the uniformity for flavors of deprecannotations, and I liked the idea of emitting the since.

But when I saw the test output, as you say, it makes the lines longer. Maybe that's OK, I don't know; it probably just looks more repetitive in the test output. If you get just a few such messages, then you want all the info, and not "re-run with -Ydeprecation-explain".

soc · 2016-04-10T11:20:14Z

Ok, maybe @lrytz has some time instead?

lrytz · 2016-04-29T09:07:27Z

src/compiler/scala/tools/nsc/Reporting.scala

+            val warningVerb   = if (numWarnings == 1) "was" else "were"
+            val warningCount  = countElementsAsString(numWarnings, s"$what warning")
+            reporter.warning(NoPosition, s"there $warningVerb $warningCount in total; re-run with ${setting.name} for details")
+          }


i would prefer to revert this part, i don't see a compelling value in including since in the summary.

The idea is to give developers a better idea which deprecations will happen in the next version versus will happen in the future. It also makes deprecations more useful for non-standard-library authors because they can prefix the version string with their library name. So it's not "20 deprecations", but "9 deprecations from the standard library which will be removed in 2.13, and 11 deprecations from library X targeted for version 5.0".

ok, works for me. cc @adriaanm, here's an example output: https://github.com/scala/scala/pull/5076/files#diff-bc1fa8bb16dc7dfb0992daa5a8051951.

should we add a comment to the deprecated scaladoc, show some example output and give a recommendation to include the library name in the since parameter, and in what format?

ping here - could you take a look at the scaladoc of class deprecated?

Just tried it out, it's pretty neat. I don't know if I'd write since="funky 0.5". But as a future feature, the compiler knows where classes come from, and sbt knows about versions. The tool can tell me since 0.5 of funky, and you're using 1.0 already. That would be handy when you're trying out recipes and you don't even know what dependency an import comes from. Then you'd realize you're reading an outdated blog post.

A trivial improvement would be to sort by since in the summary?

soc · 2016-05-19T13:16:56Z

@lrytz Tests are running! :-)

By the way, what should we do with the policy-breaking "2.11.3" deprecations? Should we change them, so that the deprecation output becomes slightly shorter/more useful?

soc · 2016-05-19T16:34:56Z

@lrytz Updated!

soc · 2016-05-20T13:17:53Z

@lrytz I think I'm know happy with it. I revised @deprecated as well as @deprecatedName, @deprecatedInheritance and @deprecatedOverriding. All of them got code examples.

Could you review?

lrytz · 2016-05-20T16:06:21Z

@soc i won't manage today, will look early next week..

soc · 2016-05-20T16:47:12Z

Thanks!

lrytz · 2016-05-23T11:26:22Z

src/library/scala/deprecated.scala

+ *  }}}
+ *
+ *  The Scala language and its standard library will only add new deprecations on major releases to
+ *  avoid the introduction of new warnings after minor version upgrades of Scala.


cc @adriaanm - agree?

I'd like to reserve the possibility to introduce deprecations during minor releases. I think this is a good compromise to speed up library evolution while maintaining our 18 month major release cadence. Error reporting configuration could use the since parameter to make only deprecations introduced in .0 releases errors, while the later ones are always warnings.

Mhh, ok. I only wanted to document the existing policy. (I tried to add minor deprecations in the past and was told, that I couldn't do that.)

Should I drop this bit?

i'd say so.

lrytz · 2016-05-23T11:29:18Z

@adriaanm please also take a quick look at f981c6d#diff-bc1fa8bb16dc7dfb0992daa5a8051951 - do you agree this is a useful addition? it goes together with the new recommendation in the deprecated API doc here: ef26ca5#diff-6d4694cf4633f1feab80a318dbb398a1R16

adriaanm · 2016-05-23T17:52:35Z

I really like include the since info in the reporting! How about only doing the group-by when compiling under -deprecation? I agree we need to balance our error reporting budget (both columns and lines).

lrytz · 2016-05-25T05:38:33Z

@adriaanm currently we print the summary ("there were n dep warns") only when -deprecation is not enabled. if it is, warnings are directly issues and you get the generic summary ("n warnings found").

do you propose to print the summary also under -deprecation, and in that case with grouping?

we could also not directly emit the warnings, but store them also under -deprecation. then we could report them by groups, instead of the order in which they come in.

adriaanm · 2016-05-25T05:58:55Z

Good point. Maybe my suggestion isn't worth the additional complexity. I like the shaming of not having acted on depreciations introduced in 2.9 :)

lrytz · 2016-05-27T13:32:38Z

LGTM - unfortunately this needs another rebase..

soc · 2016-05-29T04:09:09Z

Added @Ichoran's suggestion of ordering summarized warning messages. It's simply lexicographical order (so 2.10 comes before 2.9), but everything else would probably require tons of heuristics and guessing ...

Method `deprecationWarning` got a new parameter in scala/scala#5076.

som-snytt · 2016-06-18T04:41:25Z

Sorting may have been my suggestion. @Ichoran knows the optimal way to sort.

Stopped by to say how neat the build looks.

[quick.library] warning: there were 38 deprecation warnings (since 2.10.0)
[quick.library] warning: there were 25 deprecation warnings (since 2.11.0)
[quick.library] warning: there were two deprecation warnings (since 2.11.6)
[quick.library] warning: there were 12 deprecation warnings (since 2.12)
[quick.library] warning: there were 21 deprecation warnings (since 2.12.0)
[quick.library] warning: there were 10 deprecation warnings (since 2.12.0-M2)

Maybe someone will add an ASCII graph with versions on the x-axis.

Or like the JIRA graph, comparing the pace of new deprecations to the rate at which we still incur them.

scala-jenkins added this to the 2.12.0-M5 milestone Apr 2, 2016

som-snytt reviewed Apr 3, 2016
View reviewed changes

adriaanm assigned lrytz Apr 26, 2016

lrytz reviewed Apr 29, 2016
View reviewed changes

lrytz reviewed May 23, 2016
View reviewed changes

scala-jenkins added the reviewed label May 27, 2016

soc added 5 commits May 27, 2016 16:39

SI-9483 Add since to @deprecatedName

981e3c5

SI-9084 Add since (if available) to deprecation warnings

673350e

Lower-case spelling of @deprecated messages

5562e1a

Add since arg to deprecationWarning and use it

be38ebb

Add documentation to @deprecated

85057d5

lrytz merged commit 8f567bc into scala:2.12.x May 30, 2016

lrytz mentioned this pull request May 31, 2016

Privatize the deprecated members of immutable.Range. #5198

Merged

lrytz added a commit to lrytz/browse that referenced this pull request Jun 1, 2016

Fix signature of method overriding a method from the compiler.

8ed5d29

Method `deprecationWarning` got a new parameter in scala/scala#5076.

adriaanm added 2.12 and removed 2.12 labels Oct 29, 2016

This was referenced Apr 7, 2017

Print message and version of @deprecated in the compiler warning scala/bug#9084

Closed

Add since member to @deprecatedName scala/bug#9483

Closed

hrhino mentioned this pull request Nov 11, 2018

=typo Change all @deprecate descriptions start with upper case words. #7411

Closed

Improvements to deprecations related to since parameter #5076

Improvements to deprecations related to since parameter #5076

Uh oh!

Conversation

soc commented Apr 2, 2016

Uh oh!

soc commented Apr 3, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

som-snytt commented Apr 3, 2016

Uh oh!

soc commented Apr 3, 2016

Uh oh!

som-snytt commented Apr 3, 2016

Uh oh!

soc commented Apr 10, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soc May 1, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soc commented May 19, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

soc commented May 19, 2016

Uh oh!

soc commented May 20, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lrytz commented May 20, 2016

Uh oh!

soc commented May 20, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lrytz commented May 23, 2016

Uh oh!

adriaanm commented May 23, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lrytz commented May 25, 2016

Uh oh!

adriaanm commented May 25, 2016

Uh oh!

lrytz commented May 27, 2016

Uh oh!

soc commented May 29, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

som-snytt commented Jun 18, 2016

Uh oh!

Uh oh!

Improvements to deprecations related to `since` parameter #5076

Improvements to deprecations related to `since` parameter #5076

soc May 1, 2016 •

edited

Loading

soc commented May 19, 2016 •

edited

Loading

soc commented May 20, 2016 •

edited

Loading

adriaanm commented May 23, 2016 •

edited

Loading

soc commented May 29, 2016 •

edited

Loading