[xwiki-devs] [Proposal] Backward compatibility strategy w/ young apis included
Hi devs, Here's my effort to try to put together all that has been said… :) The idea is that whenever you change an API (adding a new one or changing an existing one) you go through the list of strategies below, trying to find the first that matches your use case. * Strategy 1 (already in place): Whenever possible don't break backward compatibility and go through a deprecation mechanism: ** Deprecate classes/methods ** Move them to Legacy modules as soon as our code is not using them anymore ** Note: No need to touch CLIRR * Strategy 2 (new): If possible, code defensively, i.e. put code in internal and open up when api is stable later on, either when users ask for it or when someone feels it's the right time ** Note: No need to touch CLIRR * Strategy 3 (new): If not possible (for example complete new modules where you wish to separate what will become stable APIs in the future from internal code) then use the @Unstable annotation at class level (or method level) ** Whenever we work on a new N.0 milestone 1 version, review all existing @Unstable annotation and for those that were added before N-1.0 remove the annotation ** Exclude the classes/methods marked @Unstable from CLIRR * Strategy 4: If the API is stable and the developers wants to break it (change of signature for example) and all other strategies don't apply, then either: ** (new) Just do it and modify the CLIRR exclude. Preferable (but not mandatory) send a NOTICE email to warn others devs that an API is going to be broken in the next release ** If not sure, send a PROPOSAL or VOTE email depending on how important you think the API to be broken is WDYT? Thanks -Vincent
Sounds good, +1 for me. On Tue, Feb 12, 2013 at 1:26 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
Here's my effort to try to put together all that has been said… :)
The idea is that whenever you change an API (adding a new one or changing an existing one) you go through the list of strategies below, trying to find the first that matches your use case.
* Strategy 1 (already in place): Whenever possible don't break backward compatibility and go through a deprecation mechanism: ** Deprecate classes/methods ** Move them to Legacy modules as soon as our code is not using them anymore ** Note: No need to touch CLIRR
* Strategy 2 (new): If possible, code defensively, i.e. put code in internal and open up when api is stable later on, either when users ask for it or when someone feels it's the right time ** Note: No need to touch CLIRR
* Strategy 3 (new): If not possible (for example complete new modules where you wish to separate what will become stable APIs in the future from internal code) then use the @Unstable annotation at class level (or method level) ** Whenever we work on a new N.0 milestone 1 version, review all existing @Unstable annotation and for those that were added before N-1.0 remove the annotation ** Exclude the classes/methods marked @Unstable from CLIRR
* Strategy 4: If the API is stable and the developers wants to break it (change of signature for example) and all other strategies don't apply, then either: ** (new) Just do it and modify the CLIRR exclude. Preferable (but not mandatory) send a NOTICE email to warn others devs that an API is going to be broken in the next release ** If not sure, send a PROPOSAL or VOTE email depending on how important you think the API to be broken is
WDYT?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
On 02/12/2013 07:26 AM, Vincent Massol wrote:
Hi devs,
Here's my effort to try to put together all that has been said… :)
The idea is that whenever you change an API (adding a new one or changing an existing one) you go through the list of strategies below, trying to find the first that matches your use case.
* Strategy 1 (already in place): Whenever possible don't break backward compatibility and go through a deprecation mechanism: ** Deprecate classes/methods ** Move them to Legacy modules as soon as our code is not using them anymore ** Note: No need to touch CLIRR
* Strategy 2 (new): If possible, code defensively, i.e. put code in internal and open up when api is stable later on, either when users ask for it or when someone feels it's the right time ** Note: No need to touch CLIRR
* Strategy 3 (new): If not possible (for example complete new modules where you wish to separate what will become stable APIs in the future from internal code) then use the @Unstable annotation at class level (or method level) ** Whenever we work on a new N.0 milestone 1 version, review all existing @Unstable annotation and for those that were added before N-1.0 remove the annotation ** Exclude the classes/methods marked @Unstable from CLIRR
I guess this has to be done manually, right?
* Strategy 4: If the API is stable and the developers wants to break it (change of signature for example) and all other strategies don't apply, then either: ** (new) Just do it and modify the CLIRR exclude. Preferable (but not mandatory) send a NOTICE email to warn others devs that an API is going to be broken in the next release ** If not sure, send a PROPOSAL or VOTE email depending on how important you think the API to be broken is
WDYT?
Sounds good. -- Sergiu Dumitriu http://purl.org/net/sergiu
On Feb 12, 2013, at 2:38 PM, Sergiu Dumitriu <[email protected]> wrote:
On 02/12/2013 07:26 AM, Vincent Massol wrote:
Hi devs,
Here's my effort to try to put together all that has been said… :)
The idea is that whenever you change an API (adding a new one or changing an existing one) you go through the list of strategies below, trying to find the first that matches your use case.
* Strategy 1 (already in place): Whenever possible don't break backward compatibility and go through a deprecation mechanism: ** Deprecate classes/methods ** Move them to Legacy modules as soon as our code is not using them anymore ** Note: No need to touch CLIRR
* Strategy 2 (new): If possible, code defensively, i.e. put code in internal and open up when api is stable later on, either when users ask for it or when someone feels it's the right time ** Note: No need to touch CLIRR
* Strategy 3 (new): If not possible (for example complete new modules where you wish to separate what will become stable APIs in the future from internal code) then use the @Unstable annotation at class level (or method level) ** Whenever we work on a new N.0 milestone 1 version, review all existing @Unstable annotation and for those that were added before N-1.0 remove the annotation ** Exclude the classes/methods marked @Unstable from CLIRR
I guess this has to be done manually, right?
right -Vincent
* Strategy 4: If the API is stable and the developers wants to break it (change of signature for example) and all other strategies don't apply, then either: ** (new) Just do it and modify the CLIRR exclude. Preferable (but not mandatory) send a NOTICE email to warn others devs that an API is going to be broken in the next release ** If not sure, send a PROPOSAL or VOTE email depending on how important you think the API to be broken is
WDYT?
Sounds good.
On Tue, Feb 12, 2013 at 2:26 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
Here's my effort to try to put together all that has been said… :)
The idea is that whenever you change an API (adding a new one or changing an existing one) you go through the list of strategies below, trying to find the first that matches your use case.
* Strategy 1 (already in place): Whenever possible don't break backward compatibility and go through a deprecation mechanism: ** Deprecate classes/methods ** Move them to Legacy modules as soon as our code is not using them anymore ** Note: No need to touch CLIRR
* Strategy 2 (new): If possible, code defensively, i.e. put code in internal and open up when api is stable later on, either when users ask for it or when someone feels it's the right time ** Note: No need to touch CLIRR
* Strategy 3 (new): If not possible (for example complete new modules where you wish to separate what will become stable APIs in the future from internal code) then use the @Unstable annotation at class level (or method level) ** Whenever we work on a new N.0 milestone 1 version, review all existing @Unstable annotation and for those that were added before N-1.0 remove the annotation
So public APIs 'automatically' become stable after 2 release cycles or after 2 final releases? E.g. if I added an API annotated with @Unstable in 4.3 then it becomes stable in 6.0M1 (because it was added before 5.0) or in 4.5? Thanks, Marius
** Exclude the classes/methods marked @Unstable from CLIRR
* Strategy 4: If the API is stable and the developers wants to break it (change of signature for example) and all other strategies don't apply, then either: ** (new) Just do it and modify the CLIRR exclude. Preferable (but not mandatory) send a NOTICE email to warn others devs that an API is going to be broken in the next release ** If not sure, send a PROPOSAL or VOTE email depending on how important you think the API to be broken is
WDYT?
Thanks -Vincent
_______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
On Feb 12, 2013, at 6:30 PM, Marius Dumitru Florea <[email protected]> wrote:
On Tue, Feb 12, 2013 at 2:26 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
Here's my effort to try to put together all that has been said… :)
The idea is that whenever you change an API (adding a new one or changing an existing one) you go through the list of strategies below, trying to find the first that matches your use case.
* Strategy 1 (already in place): Whenever possible don't break backward compatibility and go through a deprecation mechanism: ** Deprecate classes/methods ** Move them to Legacy modules as soon as our code is not using them anymore ** Note: No need to touch CLIRR
* Strategy 2 (new): If possible, code defensively, i.e. put code in internal and open up when api is stable later on, either when users ask for it or when someone feels it's the right time ** Note: No need to touch CLIRR
* Strategy 3 (new): If not possible (for example complete new modules where you wish to separate what will become stable APIs in the future from internal code) then use the @Unstable annotation at class level (or method level) ** Whenever we work on a new N.0 milestone 1 version, review all existing @Unstable annotation and for those that were added before N-1.0 remove the annotation
So public APIs 'automatically' become stable after 2 release cycles or after 2 final releases? E.g. if I added an API annotated with @Unstable in 4.3 then it becomes stable in 6.0M1 (because it was added before 5.0) or in 4.5?
If you add in 4.3M1 for example, then when we release 6.0M1 we'll automatically remove the @Unstable annotation. Of course, the developer who added it (or any other dev) can propose to remove the @Unstable annotation at any time before that, this is just a safeguard so that we don't have API that stay unstable forever… Ideally I would have preferred 1 year as the max time but IMO this is too complex to implement (since you need to track when each @Unstable annotation was added and review them all the time). I found it simpler to review once when we start developing N.0M1. Now I'm not hung on this so if someone has a better idea, please shoot. IMO we're going to need to review this anyway after we start using it and learn from experience. Note that I've just added an @Unstable annotation to 4 new methods in ModelScriptService and IMO we'll need to add some code in ScriptServiceManager to generate some logs that the user is using an unstable API (and add a per page console UI too btw). Thanks -Vincent
Thanks, Marius
** Exclude the classes/methods marked @Unstable from CLIRR
* Strategy 4: If the API is stable and the developers wants to break it (change of signature for example) and all other strategies don't apply, then either: ** (new) Just do it and modify the CLIRR exclude. Preferable (but not mandatory) send a NOTICE email to warn others devs that an API is going to be broken in the next release ** If not sure, send a PROPOSAL or VOTE email depending on how important you think the API to be broken is
WDYT?
Thanks -Vincent
FTR here's what the Hadoop project has defined: https://issues.apache.org/jira/browse/HADOOP-5073 Flume project discussing adopting the Hadoop rules: http://search-hadoop.com/m/3iHzkEPsdG1 And here are the original docs I've used in the past on the Cactus project (which led to the proposal of the "internal" package in XWiki): http://wiki.eclipse.org/Evolving_Java-based_APIs http://wiki.eclipse.org/Evolving_Java-based_APIs_2 http://wiki.eclipse.org/Evolving_Java-based_APIs_3 Package names: http://wiki.eclipse.org/Naming_Conventions#Internal_Implementation_Packages] Conclusion: I think we're good with our "internal packages" for the scope and the @Unstable annotation for the stability. Thanks -Vincent On Feb 12, 2013, at 1:26 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
Here's my effort to try to put together all that has been said… :)
The idea is that whenever you change an API (adding a new one or changing an existing one) you go through the list of strategies below, trying to find the first that matches your use case.
* Strategy 1 (already in place): Whenever possible don't break backward compatibility and go through a deprecation mechanism: ** Deprecate classes/methods ** Move them to Legacy modules as soon as our code is not using them anymore ** Note: No need to touch CLIRR
* Strategy 2 (new): If possible, code defensively, i.e. put code in internal and open up when api is stable later on, either when users ask for it or when someone feels it's the right time ** Note: No need to touch CLIRR
* Strategy 3 (new): If not possible (for example complete new modules where you wish to separate what will become stable APIs in the future from internal code) then use the @Unstable annotation at class level (or method level) ** Whenever we work on a new N.0 milestone 1 version, review all existing @Unstable annotation and for those that were added before N-1.0 remove the annotation ** Exclude the classes/methods marked @Unstable from CLIRR
* Strategy 4: If the API is stable and the developers wants to break it (change of signature for example) and all other strategies don't apply, then either: ** (new) Just do it and modify the CLIRR exclude. Preferable (but not mandatory) send a NOTICE email to warn others devs that an API is going to be broken in the next release ** If not sure, send a PROPOSAL or VOTE email depending on how important you think the API to be broken is
WDYT?
Thanks -Vincent
Hi, Thomas just raised an issue on this topic. I've added the "@unstable" annotation to a new getDocument() method he added to the XWiki class in 5.0M1 and Thomas does not think it's right to do so: https://github.com/xwiki/xwiki-platform/commit/3424896cadb3d7ec21edb002a040e... This raises the question as to when to use "@Unstable" for new APIs. I thought the strategy outlined in the mail below was clear on that but it seems not, which I why I'm sending this email. Here's my POV: " Actually I think we should always start by adding @Unstable annotations to all new APIs at least so that it can be there for a few releases to see how the API behaves and is used and give time for devs and others to give any remark about it. If we don't do this then as soon as the current version is released you're stuck with the API and have to go through deprecation if you need to modify it... better code defensively! " WDYT? Thanks -Vincent On Feb 12, 2013, at 1:26 PM, Vincent Massol <[email protected]> wrote:
Hi devs,
Here's my effort to try to put together all that has been said… :)
The idea is that whenever you change an API (adding a new one or changing an existing one) you go through the list of strategies below, trying to find the first that matches your use case.
* Strategy 1 (already in place): Whenever possible don't break backward compatibility and go through a deprecation mechanism: ** Deprecate classes/methods ** Move them to Legacy modules as soon as our code is not using them anymore ** Note: No need to touch CLIRR
* Strategy 2 (new): If possible, code defensively, i.e. put code in internal and open up when api is stable later on, either when users ask for it or when someone feels it's the right time ** Note: No need to touch CLIRR
* Strategy 3 (new): If not possible (for example complete new modules where you wish to separate what will become stable APIs in the future from internal code) then use the @Unstable annotation at class level (or method level) ** Whenever we work on a new N.0 milestone 1 version, review all existing @Unstable annotation and for those that were added before N-1.0 remove the annotation ** Exclude the classes/methods marked @Unstable from CLIRR
* Strategy 4: If the API is stable and the developers wants to break it (change of signature for example) and all other strategies don't apply, then either: ** (new) Just do it and modify the CLIRR exclude. Preferable (but not mandatory) send a NOTICE email to warn others devs that an API is going to be broken in the next release ** If not sure, send a PROPOSAL or VOTE email depending on how important you think the API to be broken is
WDYT?
Thanks -Vincent
participants (4)
-
Marius Dumitru Florea -
Sergiu Dumitriu -
Thomas Mortagne -
Vincent Massol