On 08/03/2012, at 12:37 AM, Adam Murdoch wrote: > On 07/03/2012, at 2:22 AM, Luke Daley wrote: > >> It's becoming clear that many users effectively ignore deprecation warnings. >> I think we may need to do something here. >> >> First, I don't think we can be too critical of users for this. I'm not sure >> we've been clear enough of exactly what deprecation means or how to deal >> with it, and for plugin authors it's even more confusing. >> >> I wonder if we could formalise our strategy soon after 1.0 to achieve the >> following: >> >> • Encourage users to move away from deprecated API as soon as they can so we >> don't get an influx when the item is removed > > Currently, we spit out a warning and change the samples and docs to nudge > people towards the new stuff. Any thoughts on what else we might do to > encourage people to move?
Doing a better job of saying what the replacement is would help. Also, being strict and formal about when deprecated items will removed will help. People will not be complacent about deprecation warnings as I think they are now. >> • Make it clear what the compatibility implications of a deprecation are >> (e.g. when will the deprecated item go away, what's the backwards >> compatibility story) > > Here's the contract at the moment: > > * For non-experimental things, deprecation means that the deprecated thing > will stay around until at least the next major Gradle release. > * For experimental things, deprecation means that the deprecated thing will > stay around for the current minor release only. > * For internal things, there is no deprecation. Things may change or go away > at any time. > > (assuming a scheme where major release is any version x.0.0, minor release is > x.y.0, patch release = x.y.z, snapshot is anything else. Currently we've only > been doing minor and snapshot releases). > > Some problems with things at the moment: > * It's very difficult to know what's experimental and what's not. > * The deprecation warning is a bit vague about when the feature will go away > (actually, it's not vague - it's usually wrong). > * The DSL reference does not tell you what is deprecated nor when the feature > will go away. > * There's nothing about this contract in the 'how to write a build script' > and the 'how to write a plugin' user guide chapters. > * Our versioning scheme doesn't really communicate any semantics (but that > will go away soon). Very concise summary. Addressing these points would take us a long way there. >> • Establish boundaries for version compatibility to help plugin authors > > The current contract: > * A plugin or task type that does not use any experimental features, continue > to work in binary form until at least the next major Gradle release. > * A plugin or task type that uses experimental features will work for the > current minor release only. > * A plugin or task type that uses internal features will work only for the > release it was compiled against. > > Same problems with this contract, as for build scripts above. Right. So we know what the problems are, we just need to do the work to address them. -- Luke Daley Principal Engineer, Gradleware http://gradleware.com
