-
Notifications
You must be signed in to change notification settings - Fork 3.1k
Improvements to deprecations related to since
parameter
#5076
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
Review by @SethTisue? |
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) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
?w=1
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 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. |
The whole reason why 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 (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:
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. |
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". |
Ok, maybe @lrytz has some time instead? |
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") | ||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i would prefer to revert this part, i don't see a compelling value in including since
in the summary.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ok, works for me. cc @adriaanm, here's an example output: https://github.com/scala/scala/pull/5076/files#diff-bc1fa8bb16dc7dfb0992daa5a8051951.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ping here - could you take a look at the scaladoc of class deprecated
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
@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? |
@lrytz Updated! |
@lrytz I think I'm know happy with it. I revised Could you review? |
@soc i won't manage today, will look early next week.. |
Thanks! |
* }}} | ||
* | ||
* 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
cc @adriaanm - agree?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i'd say so.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.
@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 |
I really like include the |
@adriaanm currently we print the summary ("there were n dep warns") only when do you propose to print the summary also under we could also not directly emit the warnings, but store them also under |
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 :) |
LGTM - unfortunately this needs another rebase.. |
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.
Sorting may have been my suggestion. @Ichoran knows the optimal way to sort. Stopped by to say how neat the build looks.
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. |
No description provided.