[DISCUSS] Add a "Beta" badge in the documentation to components in flink-staging

[Robert Metzger]

Hi,

In an offline discussion with other Flink committers, we came up with the
idea to mark new components from the "flink-staging" module with a "Beta"
badge in the documentation.
This way, we make it very clear that the component is still under heavy
development.

If we agree on this, I'll file a JIRA and add the badge to the
documentation.


Best,
Robert

[Chiwan Park]

+1

Good idea. Users can accept API changes of “flink-staging” module with “Beta" badge.

Regards.
Chiwan Park (Sent with iPhone)

> On Mar 29, 2015, at 11:38 PM, Robert Metzger <[hidden email]> wrote:
>
> Hi,
>
> In an offline discussion with other Flink committers, we came up with the
> idea to mark new components from the "flink-staging" module with a "Beta"
> badge in the documentation.
> This way, we make it very clear that the component is still under heavy
> development.
>
> If we agree on this, I'll file a JIRA and add the badge to the
> documentation.
>
>
> Best,
> Robert

[Till Rohrmann]

+1

On Sun, Mar 29, 2015 at 5:04 PM, Chiwan Park <[hidden email]> wrote:

> +1
>
> Good idea. Users can accept API changes of “flink-staging” module with
> “Beta" badge.
>
> Regards.
> Chiwan Park (Sent with iPhone)
>
>
> > On Mar 29, 2015, at 11:38 PM, Robert Metzger <[hidden email]>
> wrote:
> >
> > Hi,
> >
> > In an offline discussion with other Flink committers, we came up with the
> > idea to mark new components from the "flink-staging" module with a "Beta"
> > badge in the documentation.
> > This way, we make it very clear that the component is still under heavy
> > development.
> >
> > If we agree on this, I'll file a JIRA and add the badge to the
> > documentation.
> >
> >
> > Best,
> > Robert
>
>

[Stephan Ewen]

I also like the idea

+1

There was a discussion about tagging public API classes and methods, to
make it very clear what APIs should be stable across versions and what
might change.

Can we solve these things together:

public class ApiVisibility {

    public static @interface Public {};
    public static @interface PublicBeta {};
    public static @interface Internal{};

   private ApiVisibility () {}
}

@ApiVisibility.Public
public class SomeApiClass {
}

@ApiVisibility.PublicBeta
public class EvolvingClass {
}

@ApiVisibility.Internal
public class RuntimeClass {
}


Names are subject to debate ;-)




On Sun, Mar 29, 2015 at 5:04 PM, Chiwan Park <[hidden email]> wrote:

> +1
>
> Good idea. Users can accept API changes of “flink-staging” module with
> “Beta" badge.
>
> Regards.
> Chiwan Park (Sent with iPhone)
>
>
> > On Mar 29, 2015, at 11:38 PM, Robert Metzger <[hidden email]>
> wrote:
> >
> > Hi,
> >
> > In an offline discussion with other Flink committers, we came up with the
> > idea to mark new components from the "flink-staging" module with a "Beta"
> > badge in the documentation.
> > This way, we make it very clear that the component is still under heavy
> > development.
> >
> > If we agree on this, I'll file a JIRA and add the badge to the
> > documentation.
> >
> >
> > Best,
> > Robert
>
>

[Henry Saputra]

+1 to this.

Was thinking about the same thing.

- Henry



On Sun, Mar 29, 2015 at 7:38 AM, Robert Metzger <[hidden email]> wrote:

> Hi,
>
> In an offline discussion with other Flink committers, we came up with the
> idea to mark new components from the "flink-staging" module with a "Beta"
> badge in the documentation.
> This way, we make it very clear that the component is still under heavy
> development.
>
> If we agree on this, I'll file a JIRA and add the badge to the
> documentation.
>
>
> Best,
> Robert

[mxm]

+1 for using annotations to mark the status of API classes/methods. I think
that is very good practice to manage backwards-compatibility.

On Sun, Mar 29, 2015 at 8:20 PM, Henry Saputra <[hidden email]>
wrote:

> +1 to this.
>
> Was thinking about the same thing.
>
> - Henry
>
>
>
> On Sun, Mar 29, 2015 at 7:38 AM, Robert Metzger <[hidden email]>
> wrote:
> > Hi,
> >
> > In an offline discussion with other Flink committers, we came up with the
> > idea to mark new components from the "flink-staging" module with a "Beta"
> > badge in the documentation.
> > This way, we make it very clear that the component is still under heavy
> > development.
> >
> > If we agree on this, I'll file a JIRA and add the badge to the
> > documentation.
> >
> >
> > Best,
> > Robert
>

[Robert Metzger]

I filed the JIRA for the beta badge:
https://issues.apache.org/jira/browse/FLINK-1800

On Mon, Mar 30, 2015 at 12:34 PM, Maximilian Michels <[hidden email]> wrote:

> +1 for using annotations to mark the status of API classes/methods. I think
> that is very good practice to manage backwards-compatibility.
>
> On Sun, Mar 29, 2015 at 8:20 PM, Henry Saputra <[hidden email]>
> wrote:
>
> > +1 to this.
> >
> > Was thinking about the same thing.
> >
> > - Henry
> >
> >
> >
> > On Sun, Mar 29, 2015 at 7:38 AM, Robert Metzger <[hidden email]>
> > wrote:
> > > Hi,
> > >
> > > In an offline discussion with other Flink committers, we came up with
> the
> > > idea to mark new components from the "flink-staging" module with a
> "Beta"
> > > badge in the documentation.
> > > This way, we make it very clear that the component is still under heavy
> > > development.
> > >
> > > If we agree on this, I'll file a JIRA and add the badge to the
> > > documentation.
> > >
> > >
> > > Best,
> > > Robert
> >
>