You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@brooklyn.apache.org by Aled Sage <al...@gmail.com> on 2015/08/17 23:03:23 UTC
Deprecation guarantees/policy?
Hi all,
We should think about + document our deprecation policy - I can't find
it in our docs [1].
I could only find a pre-apache mailing list conversation
(brooklyn-dev@googlegroups.com, from 5/9/12) where we proposed:
While we're still at 0.x, we keep deprecated methods for one release
(e.g. if deprecated in 0.4.0-SNAPSHOT, then it will be in 0.4 and
deleted for 0.5.
When we get to >= 1.x, then we keep it for two releases.
Note that semantic versioning [2] would have us go from 1.x to 2.y
before we can delete anything from the public API (except in 0.x releases).
Defining how much of the code is the "public API" is another question.
---
The other thing to document is guidelines for using @Deprecated. We
could say:
* Always include @deprecated in javadoc
e.g. "@deprecated since 0.7.0; instead use {@link ...}"
o say when it was deprecated
o say what to use instead - e.g. link to alternative method,
and/or code snippet, etc
* Consider including a log.warn when a deprecated method or config
option is used, saying who is using it (e.g. useful if deprecated
config keys are used in yaml).
(if it's a method which might be called a lot, some convenience for
"warn once per entity" would be helpful)
* Link to [3]
We should also try to consistently use @Since for new classes/methods
being added.
Aled
p.s. Of course this is a tricky time to discuss deprecation: our current
package renames will definitely not follow any such deprecation policy!
[1] https://brooklyn.incubator.apache.org/documentation
[2] http://semver.org/
[3]
https://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/deprecation/deprecation.html
Re: Deprecation guarantees/policy?
Posted by Aled Sage <al...@gmail.com>.
Thanks Mike, I've merged your PR. All, which covers the second part
(i.e. guidelines for using @Deprecated).
We still need to reach agreement on our deprecation policy.
Aled
On 18/08/2015 19:29, Mike Zaccardo wrote:
> +1 deprecation guidelines that you proposed.
>
> I created a PR[1] adding them to the dev guide on the website. We can
> tweak the wording there, if need be.
>
> Cheers,
> Mike
>
> [1] https://github.com/apache/incubator-brooklyn/pull/843
>
> On Mon, Aug 17, 2015 at 2:03 PM, Aled Sage <al...@gmail.com> wrote:
>
>> Hi all,
>>
>> We should think about + document our deprecation policy - I can't find it
>> in our docs [1].
>>
>> I could only find a pre-apache mailing list conversation (
>> brooklyn-dev@googlegroups.com, from 5/9/12) where we proposed:
>>
>> While we're still at 0.x, we keep deprecated methods for one release
>> (e.g. if deprecated in 0.4.0-SNAPSHOT, then it will be in 0.4 and
>> deleted for 0.5.
>> When we get to >= 1.x, then we keep it for two releases.
>>
>> Note that semantic versioning [2] would have us go from 1.x to 2.y before
>> we can delete anything from the public API (except in 0.x releases).
>>
>> Defining how much of the code is the "public API" is another question.
>>
>> ---
>> The other thing to document is guidelines for using @Deprecated. We could
>> say:
>>
>> * Always include @deprecated in javadoc
>> e.g. "@deprecated since 0.7.0; instead use {@link ...}"
>> o say when it was deprecated
>> o say what to use instead - e.g. link to alternative method,
>> and/or code snippet, etc
>> * Consider including a log.warn when a deprecated method or config
>> option is used, saying who is using it (e.g. useful if deprecated
>> config keys are used in yaml).
>> (if it's a method which might be called a lot, some convenience for
>> "warn once per entity" would be helpful)
>> * Link to [3]
>>
>> We should also try to consistently use @Since for new classes/methods
>> being added.
>>
>> Aled
>>
>> p.s. Of course this is a tricky time to discuss deprecation: our current
>> package renames will definitely not follow any such deprecation policy!
>>
>> [1] https://brooklyn.incubator.apache.org/documentation
>> [2] http://semver.org/
>> [3]
>> https://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/deprecation/deprecation.html
>>
>>
Re: Deprecation guarantees/policy?
Posted by Mike Zaccardo <mi...@cloudsoftcorp.com>.
+1 deprecation guidelines that you proposed.
I created a PR[1] adding them to the dev guide on the website. We can
tweak the wording there, if need be.
Cheers,
Mike
[1] https://github.com/apache/incubator-brooklyn/pull/843
On Mon, Aug 17, 2015 at 2:03 PM, Aled Sage <al...@gmail.com> wrote:
> Hi all,
>
> We should think about + document our deprecation policy - I can't find it
> in our docs [1].
>
> I could only find a pre-apache mailing list conversation (
> brooklyn-dev@googlegroups.com, from 5/9/12) where we proposed:
>
> While we're still at 0.x, we keep deprecated methods for one release
> (e.g. if deprecated in 0.4.0-SNAPSHOT, then it will be in 0.4 and
> deleted for 0.5.
> When we get to >= 1.x, then we keep it for two releases.
>
> Note that semantic versioning [2] would have us go from 1.x to 2.y before
> we can delete anything from the public API (except in 0.x releases).
>
> Defining how much of the code is the "public API" is another question.
>
> ---
> The other thing to document is guidelines for using @Deprecated. We could
> say:
>
> * Always include @deprecated in javadoc
> e.g. "@deprecated since 0.7.0; instead use {@link ...}"
> o say when it was deprecated
> o say what to use instead - e.g. link to alternative method,
> and/or code snippet, etc
> * Consider including a log.warn when a deprecated method or config
> option is used, saying who is using it (e.g. useful if deprecated
> config keys are used in yaml).
> (if it's a method which might be called a lot, some convenience for
> "warn once per entity" would be helpful)
> * Link to [3]
>
> We should also try to consistently use @Since for new classes/methods
> being added.
>
> Aled
>
> p.s. Of course this is a tricky time to discuss deprecation: our current
> package renames will definitely not follow any such deprecation policy!
>
> [1] https://brooklyn.incubator.apache.org/documentation
> [2] http://semver.org/
> [3]
> https://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/deprecation/deprecation.html
>
>
--
Cloudsoft Corporation Limited, Registered in Scotland No: SC349230.
Registered Office: 13 Dryden Place, Edinburgh, EH9 1RP
This e-mail message is confidential and for use by the addressee only. If
the message is received by anyone other than the addressee, please return
the message to the sender by replying to it and then delete the message
from your computer. Internet e-mails are not necessarily secure. Cloudsoft
Corporation Limited does not accept responsibility for changes made to this
message after it was sent.
Whilst all reasonable care has been taken to avoid the transmission of
viruses, it is the responsibility of the recipient to ensure that the
onward transmission, opening or use of this message and any attachments
will not adversely affect its systems or data. No responsibility is
accepted by Cloudsoft Corporation Limited in this regard and the recipient
should carry out such virus and other checks as it considers appropriate.