On Oct 29, 2014, at 10:26 AM, Colin Dixon <colin@...> wrote:

I think we have three threads going on:

1.) Not everyone likes the term Legacy and I actually agree with Chris that Stable is a lot better. The definition actually does match that since it says those APIs should remain the same (stable) throughout the release. Supported says bad things about the other APIs that I don't think we want to imply. My vote would be for Stable.

2.) We desperately need tools to help us track APIs, who's using them (across projects) and what state they're in. This is true and I'd love to see us develop some of these tools, perhaps as part of existing/new releng projects.

3.) In the shorter run, I'd really like to see somebody write up simple documentation/tutorials about how people can limit the visibility of their APIs both in pom files and with java keywords.

Exploring using annotations seems like another great idea, but with the exception of @Deprecated, do any of them show up in a visible way for developers? It seems like we'd need a corresponding Eclipse plugin to help most of our developers understand when they were using different kinds of APIs and the expectations they come with.

--Colin

On Fri, Oct 24, 2014 at 10:13 PM, Abhijit Kumbhare <abhijitkoss@...> wrote:

About:

Hrm, you don't like Stable, I don't like Legacy.  Only other word that
springs to mind is Supported.  I do think Stable conveys the right
message, i.e. it won't change on you.

How about "pre-existing" API?

 

On Fri, Oct 24, 2014 at 5:40 PM, Chris Wright <chrisw@...> wrote:

* Robert Varga (nite@...) wrote:
> On 10/24/2014 08:49 PM, Chris Wright wrote:
> >* Colin Dixon (colin@...) wrote:
> >>The draft release plan that Phil and I have been working on is ready for
> >>comments. You can find it here:
> >>https://wiki.opendaylight.org/view/Simultaneous_Release:DRAFT_Lithium_Release_Plan_ckd
> >I think a Legacy API sounds like something old where there is also a
> >newer way to do the same thing.  I'd suggest Stable API.
> >
> >I don't understand this part of Provisional API:
> >
> >   "...or an externally accessible API that existed in a previous version
> >    of ODL but is being modified for the current release."
> >
> >The part that is unclear to me is the state the API was in during the
> >previous version.  IOW, to me it _had_ to be Provisional to begin with,
> >else you couldn't change it.  If it was Legacy (Stable?) to begin with,
> >then this is a _new_ API, and certainly the new API is Provisional.
> >
> >Also, I think the APIs should be marked in code, annotations being one
> >obvious way to do it (in today's call we touched on deprecated, and only
> >exporting supported APIs)?  The ability to enumerate externally consumable
> >APIs should be automated, and even better, the API state marked in the
> >code so that it's clear to the consumer what contract you are receiving.
>
> Unfortunately, we have had little consensus on the fact that we should be
> marking APIs.

I think it's a good idea, what is your opinion?

> We currently completely lack the tools to do so in the models, too.

Do you think that's an insurmountable issue or more a matter of someone
w/ the time to do this work?  I'm assuming the later given your reference
to @Deprecated and @Beta w/ yangtools.

> I would hate to associate the word 'stable' with an API. In confers a sense
> of matureness simply not present in a lot of Helium APIs.

Hrm, you don't like Stable, I don't like Legacy.  Only other word that
springs to mind is Supported.  I do think Stable conveys the right
message, i.e. it won't change on you.

> I think clarifying/documenting the API intent in the early stages of this
> particular release is a good thing, simply because it has not really
> happened in the last release.

Yeah, I agree.

> At this point we do not have a clear proposal on how to mark the APIs, much
> less a proven mechanism. I think that disqualifies it from being mandatory
> in this release, but yes, we need something going forward. Yangtools has
> trailblazed with using @Deprecated and @Beta, but the problem is a lot more
> complicated than that, and most of our code does not even use the visibility
> modifiers properly -- any taker for writing a guideline?

To be clear, I'm not suggesting mandatory.  I am suggesting that we
support being clear in the code so that we can enumerate w/out that
being manual (the template requires submitting a list of APIs which
strikes me as a waste of time if we can generate the list), and clearly
show the API status to consumers through annotations, javadoc, etc.

What I've seen in Spark fairly typical annotation def'n:

@Retention(value=RUNTIME)
@Target(value={TYPE,FIELD,METHOD,PARAMETER,CONSTRUCTOR,LOCAL_VARIABLE,PACKAGE})
public @interface Experimental

Would it be useful to have org.opendaylight.annotation?

thanks,
-chris

_______________________________________________
TSC mailing list
TSC@...
https://lists.opendaylight.org/mailman/listinfo/tsc

_______________________________________________
TSC mailing list
TSC@...
https://lists.opendaylight.org/mailman/listinfo/tsc

_______________________________________________
TSC mailing list
TSC@...
https://lists.opendaylight.org/mailman/listinfo/tsc