8 Feb
2013
8 Feb
'13
11:42 a.m.
On Feb 8, 2013, at 11:18 AM, Vincent Massol <vincent(a)massol.net> wrote:
On Feb 7, 2013, at 5:52 PM, Vincent Massol <vincent(a)massol.net> wrote:
Actually, reading further it seems only one user has an issue with the @Beta annotation
and others find it acceptable.
ok so here's the summary of the brainstorming so far:
* Proposal 1 (internal package):
- Vincent
- Marius
* Proposal 2 (experimental package)
- Caleb
* Proposal 3 (@Beta/@Experimental annotation)
- Thomas
- Edy
* Other proposal
- Denis (use 1) for small changes and only use RN to mark new module as experimental)
Note that with proposal 3 we also need to remember 2 things:
- we'll need to add CLIRR excludes but that can be done globally using the global
exclude so not too painful
- we'll need to detail how long is the @Beta annotation supposed to stay. If it stays
forever it's the same syndrome as never releasing a 1.0 version which doesn't help
because people will use it in production anyway if it's too long to be 1.0. So
proposal 3 needs to have a max timeframe. IMO a full cycle would be a good max time to
remain @Beta annotations. So if you add the @Beta in version N.P we have to remove it
before N+2.0 (in practice that's a max time of 1.5 years). We could also say N+1.P but
it's harder to remember since it means verifying at each release whereas N+1.P means
verifying only once.
Personally I'm ok to try option 3 since I'd like to make progress on this.
WDYT?
Thanks
-Vincent
FWIW Guava is using a @Beta annotation:
http://code.google.com/p/guava-libraries/
Extract:
"
APIs marked with the @Beta annotation at the class or method level are subject to change.
They can be modified in any way, or even removed, in any major release. If your code is a
library itself (i.e. it is used on the CLASSPATH of users outside your own control), you
should not use beta APIs, unless you repackage them (e.g. using ProGuard). Here is a
current list of all the beta APIs.
Serialized forms of ALL objects are subject to change. Do not persist these and assume
they can be read by a future version of the library.
Deprecated non-beta APIs will be removed eighteen months after the release in which they
are first deprecated. You must fix your usages before this time. If you don't, any
manner of breakage might result (you are not guaranteed a compilation error).
"
Interestingly a user points out the issue I had with using an annotation, see the
comments in http://code.google.com/p/guava-libraries/wiki/Release10:
Extract:
"
My understandig of @Beta is, that these are the higly unstable parts of guava, so I
don't want to use them (and I guess most developers don't want to because why
should anybody make his lives more difficult when moving to the next version).
But how do I do that? I don't want to look all the time at the source code when
programming to make sure I didn't use the beta parts. Code completion knows nothing
about @Beta (and it shouldn't!). Hence I have to remove all the beta parts. But why
should the user handle the repackaging thing when you can simple release two versions: a
beta / instable version and a stable / release version. Simple as that. Anybody can use
the version he likes.
Other OSS projects handle this much better. The same goes vor versioning, naming,
packaging, downloading, etc. E. g. I never had such fruitless discussions with Apache
software (and in case Apache commons collection ever releases a "generified"
version, I'll most certainly switch back to that).
" Thanks
-Vincent
Thanks
-Vincent
On May 3, 2012, at 9:47 AM, Vincent Massol <vincent(a)massol.net> wrote:
Hi devs,
We have recently voted a rule where we said that we will do the following:
* Always deprecate APIs
* Always move them to Legacy modules
* And when there's a technical issue to moving stuff to the Legacy module, only then,
send a VOTE to remove an API
(see http://markmail.org/message/tino4ngttflc5i3s).
This means that from now on (starting on 26th of April 2012) we're not allowed to
put excludes in CLIRR.
However I've seen that we have added some CLIRR excludes after the vote was passed.
I believe that the main issue we have is for "young" APIs that are not
considered stable.
Proposal 1: Internal package
=========
* Young APIs must be located in the "internal" package till they become stable.
I propose "internal" to reuse an existing package that we filter when testing
for CLIRR. "internal" means that users should not use this API because it's
considered unstable and can change at any time.
* When a Young API is considered stable enough and we want to open it to public
consumption then we move it from "internal" to its target package (that's
easy to with IDEs). From that point forward any changes to them goes through the standard
mechanism of deprecation/legacy.
* If we want to add a new method to an existing public API then this should not be
considered a "young" API. It's just an addition to an existing API and thus
goes directly to the deprecation/legacy cycle.
* We need to be careful to isolate "young" APIs from public API so that users
don't inadvertently use "young" unstable APIs by mistake. If not possible
then directly go through the deprecation/legacy cycle.
The advantage of this proposal is that it doesn't change our current practices and is
very easy to verify through CLIRR.
Proposal 2: Experimental package
=========
Another possibility I can think of is to introduce a new "experimental" package
instead of reusing the "internal" one. It has the advantage of being able to
follow "young" APIs and ensure they don't stay in that state indefinitely,
while still allowing the user who uses it to notice it's experimental.
Proposal 3: Experimental Annotation
=========
Another idea is to just use an @Experimental javadoc tag for experimental code. It has
the advantage of using the target package but it has drawbacks:
* It's impossible for users to notice that they're using Experimental APIs since
when they import a class they won't see anything that'll tell them they're
using a "young" API
* It's almost impossible to tell CLIRR to exclude those APIs from its checks. The
only way to do this is to modify the source code of the CLIRR plugin AFAIK. Thus we would
need to exclude those manually using CLIRR excludes and thus before we release we would
need to go over the full list of CLIRR excludes to ensure the excludes listed are only for
"young" APIs marked "experimental".
Note that I mentioned javadoc tag and not annotation because I believe we need to add
information about when the Experimental API was first introduced so that we eventually
move it as a proper API by removing the Experimental tag. Maybe we would need a rule such
as: keep that tag for less or equal to 3 full minor releases (i.e. 6 months).
WDYT? Any other idea?
Thanks
-Vincent