Consider @Experimental / @ApiMayChange markers on APIs - LOOKING FOR NAMES #438

Closed
ktoso opened this Issue Oct 26, 2016 · 10 comments

Projects

None yet

4 participants

@ktoso
Member
ktoso commented Oct 26, 2016

No description provided.

@patriknw
Member

Experimental means so many different things for different people. Shall we try another name?

@ApiMayChange ?

@ktoso ktoso changed the title from Consider @Experimental markers on APIs to Consider @Experimental / @ApiMayChange markers on APIs - LOOKING FOR NAMES Oct 26, 2016
@ktoso
Member
ktoso commented Oct 26, 2016

Yeah, absolutely let's talk about the names to use here.
I think the Hadoop ecosystem has started using various annotations like that years ago as well, let's see if naming there could inspire us. Names that have good meaning would be best here than the experimental which in Akka up until this day even people are confused about

@ktoso ktoso referenced this issue in akka/akka-meta Oct 26, 2016
Closed

Akka HTTP, free 4 all call #34

8 of 8 tasks complete
@ktoso ktoso added the discuss label Oct 26, 2016
@ktoso
Member
ktoso commented Nov 2, 2016

One I'd like to add is something among the lines of @NotMeantToBeExtended - specifically for the HTTP model.

@jonas
Contributor
jonas commented Dec 7, 2016

Here's a link to Spark's API annotations some of which looks to be overlapping: https://github.com/apache/spark/tree/master/common/tags/src/main/java/org/apache/spark/annotation

As for name Spark use InterfaceStability.

@patriknw
Member
patriknw commented Dec 8, 2016

Something like that looks good. I think we should use same in Akka core. Perhaps Stable is the default if no annotation is given.

@jlprat
Contributor
jlprat commented Dec 8, 2016

@ktoso for the "Not meant to be extended", I know JBoss Drools packs all those classes under the internal package. It's pretty clear that if you depend on something under the internal package, you can't expect stability, or actually relay in any way on this.

@ktoso
Member
ktoso commented Dec 8, 2016

Due to the design of our HTTP Model it is "not meant to be extended" however it is very much public API. It can not be final, due to scaladsl is-a javadsl - this saves impl complexity and allocations :)

Will think and propose names soon, feel free to propose some :)

@jlprat
Contributor
jlprat commented Dec 8, 2016

I see... then the internal makes no sense

@ktoso ktoso added this to the 10.0.2 milestone Jan 6, 2017
@ktoso ktoso self-assigned this Jan 6, 2017
@ktoso
Member
ktoso commented Jan 6, 2017

Let's start simple:

  • @InternalAPI - equivalent of current /** INTERNAL API*/ comments, we'll work on MiMa to be aware of these (!) so no filtering out when touching such classes/methods will be needed
  • @APIMayChange - To mark new "experimental" APIs, such as the #662 API

These annotations will land immediately in akka.actor, we'll use them from there in Akka HTTP.

Hope this sounds good, cheers!

@ktoso ktoso referenced this issue in akka/akka Jan 6, 2017
Closed

Introduce API stability annotations #22109

@ktoso
Member
ktoso commented Jan 6, 2017

This will be sovled in Akka itself .
PR for annotations in Akka: akka/akka#22110

@ktoso ktoso closed this Jan 6, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment