Honestly, I think APIs could be pretty simply defined if you think of it in terms of the user:
@Deprecated = this was either stable or evolve but the functionality/interface will go away at a future date @Stable = the user of this API opting out of changes to functionality and interface. For example, default options don't change for a transform annotated this way. Evolving (No Annotation) = the user is opting in to changes to functionality but not to interface. We should generally try to write backwards compatible code, but on the other hand the release model does not force users into an upgrade @Experimental = this functionality / interface might be a bad idea and could go away at any time On Mon, Apr 3, 2023 at 7:22 AM Danny McCormick via dev <dev@beam.apache.org> wrote: > *;tldr - I'd like "evolving" to be further defined, specifically around > how we will make decisions about breaking behavior and API changes* > > I don't particularly care what tags we use as long as they're well > documented. With that said, I think the following framing needs to be > documented with more definition to flesh out the underlying philosophy: > > *> - new code is changeable/evolving by default (so we don't have to > always remember to annotate it) but users have confidence they can use it > in production (because we have good software engineering practices)* > > * > - Experimental would be reserved for more risky things* > * > - after we are confident an API is stable, because it has been the > same across a couple releases, we mark it* > > Here, we have 3 classes of APIs - "experimental", "stable", and "evolving" > (or alternately "undefined"). > > "Experimental" seems clear - we can make any changes we want. "Stable" is > reasonably straightforward as well - we will only make non-breaking changes > except in exceptional cases (e.g. security hole, total failure of > functionality, etc...) > > With "evolving" is the idea that we can still make any changes we want, > but we think it's less likely we'll need to? Are silent behavior changes > acceptable here (my vote would be no)? What about breaking API changes (my > vote would be rarely)? > > I think being able to change our APIs is an ok goal, but outside of a true > experimental context we should still be weighing the cost of API changes > against the benefit; we have a problem of people not updating to newer > SDKs, and introducing more breaking changes will just exacerbate that > problem. Maybe my concerns are just a consequence of me not really seeing > the same things that you're seeing, specifically: "*I'm seeing a culture > of being afraid to change things, even when it would be good for users, > because our API surface area is far too large and not explicitly chosen.*" > Mostly what I've seen is a healthy concern about making it hard for users > to upgrade versions, but my view is probably just limited here. > > My ideal framing for "evolving" is: an *evolving* API can make breaking > API changes between versions, but this will be rare and weighed against the > cost of slowing users' upgrade process. All breaking changes will be > communicated in our change log. An *evolving* API will not make silent > behavior changes except in exceptional cases (e.g. patching a security gap, > fixing total failures of functionality). > > Thanks, > Danny > > On Mon, Apr 3, 2023 at 9:02 AM Jan Lukavský <je...@seznam.cz> wrote: > >> Hi, >> >> removing @Experimental and adding explicit @Stable annotation makes >> sense to me. FWIW, when we were designing Euphoria API, we adopted the >> following convention: >> >> - the default stability of "evolving", @Experimental for really >> experimental code [1] >> >> - target @Audience of API [2] (pipeline author, runner, internal, test) >> >> - and @StateComplexity of operators (PTransforms) [3] >> >> The last part is something that was planned to be used by tools that can >> analyze the Pipeline for performance or visualize which transform(s) are >> most state-consuming. But this ended only as plans. :) >> >> Jan >> >> [1] >> >> https://github.com/apache/beam/blob/master/sdks/java/extensions/euphoria/src/main/java/org/apache/beam/sdk/extensions/euphoria/core/annotation/stability/Experimental.java >> >> [2] >> >> https://github.com/apache/beam/blob/master/sdks/java/extensions/euphoria/src/main/java/org/apache/beam/sdk/extensions/euphoria/core/annotation/audience/Audience.java >> >> [3] >> >> https://github.com/apache/beam/blob/master/sdks/java/extensions/euphoria/src/main/java/org/apache/beam/sdk/extensions/euphoria/core/annotation/operator/StateComplexity.java >> >> >> On 3/31/23 23:05, Kenneth Knowles wrote: >> > Hi all, >> > >> > Long ago, we adopted two annotations in Beam to communicate to users: >> > >> > - `@Experimental` indicates that an API might change >> > - `@Internal` indicates that an API is not meant for users. >> > >> > I've seen some real problems with this approach: >> > >> > - Users are afraid to use `@Experimental` APIs, because they are >> > worried they are not production-ready. But it really just means they >> > might change, and has nothing to do with that. >> > - People write new code and do not put `@Experimental` annotations on >> > it, even though it really should be able to change for a while, so we >> > can do a good job. >> > - I'm seeing a culture of being afraid to change things, even when it >> > would be good for users, because our API surface area is far too large >> > and not explicitly chosen. >> > - `@Internal` is not that well-known. And now we have many target >> > audiences: Beam devs, PTransform devs, tool devs, pipeline authors. >> > Some of them probably want to use `@Internal` stuff! >> > >> > I looked at a couple sibling projects and what they have >> > - Flink: >> > - Spark: >> > >> > They have many more tags, and some of them seem to have reverse >> > defaults to Beam. >> > >> > Flink: >> > >> https://github.com/apache/flink/tree/master/flink-annotations/src/main/java/org/apache/flink/annotation >> > >> > - Experimental >> > - Internal.java >> > - Public >> > - PublicEvolving >> > - VisibleForTesting >> > >> > Spark: >> > >> https://github.com/apache/spark/tree/master/common/tags/src/main/java/org/apache/spark/annotation >> and >> >> > >> https://github.com/apache/spark/tree/master/common/tags/src/main/scala/org/apache/spark/annotation >> > >> > - AlphaComponent >> > - DeveloperApi >> > - Evolving >> > - Experimental >> > - Private >> > - Stable >> > - Unstable >> > - Since >> > >> > I think it would help users to understand Beam with some simple, >> > though possibly large-scale changes. My goal would be: >> > >> > - new code is changeable/evolving by default (so we don't have to >> > always remember to annotate it) but users have confidence they can use >> > it in production (because we have good software engineering practices) >> > - Experimental would be reserved for more risky things >> > - after we are confident an API is stable, because it has been the >> > same across a couple releases, we mark it >> > >> > A concrete proposal to achieve this would be: >> > >> > - Add a @Stable annotation and use it as appropriate on our primary >> APIs >> > - [Possibly] add an @Evolving annotation that would also be the >> default. >> > - Remove most `@Experimental` annotations or change them to `@Evolving` >> > - Communicate about this (somehow). If possible, surface the >> > `@Evolving` default in documentation. >> > >> > The last bit is the hardest. >> > >> > Kenn >> >
