Apache Yetus Interface Taxonomy: Audience and Stability Classification

Motivation

The interface taxonomy classification provided by Apache Yetus annotations is for guidance to developers and users of interfaces. The classification guides a developer to declare the targeted audience or users of an interface and also its stability.

Interface Classification

Yetus provides the following interface classification, derived from the
OpenSolaris taxonomy
and, to some extent, from taxonomy used inside Yahoo.
Interfaces have two main attributes: Audience and Stability

Audience

Audience denotes the potential consumers of the interface. While many interfaces are internal/private to the implementation, others are public/external interfaces and are meant for wider consumption by applications and/or clients. For example, POSIX definitions in libc are external, while large parts of the kernel are internal or private interfaces. Also, some interfaces are targeted towards other specific subsystems.

Identifying the audience of an interface helps define the impact of breaking
it. For instance, it might be okay to break the compatibility of an interface
whose audience is a small number of specific subsystems. On the other hand, it
is probably not okay to break a protocol interfaces that millions of Internet
users depend on.

Yetus uses the following kinds of audience in order of increasing/wider visibility:

Private

The interface is for internal use within a project(such as Apache Hadoop)
and should not be used by applications or by other projects. It is subject to
change at anytime without notice. Most interfaces of a project are Private (also referred to as project-private).

Limited-Private

The interface is used by a specified set of projects or systems (typically
closely related projects). Other projects or systems should not use the
interface. Changes to the interface will be communicated/ negotiated with the
specified projects. For example, in the Apache Hadoop project, some interfaces are LimitedPrivate{HDFS, MapReduce} in that they are private to the HDFS and
MapReduce subprojects.

Public

The interface is for general use by any application.

Stability

Stability denotes how stable an interface is, as in when incompatible changes to
the interface are allowed. Yetus provides the following levels of stability.

Stable

Can evolve while retaining compatibility for minor release boundaries; in other
words, incompatible changes to APIs marked Stable are generally only allowed
at major releases (i.e. at m.0).

Evolving

Evolving, but incompatible changes are allowed at minor release (i.e. m .x)

Unstable

Incompatible changes to Unstable APIs are allowed any time. This usually makes
sense for only private interfaces.

However one may call this out for a supposedly public interface to highlight
that it should not be used as an interface; for public interfaces, labeling it
as Not-an-interface is probably more appropriate than "Unstable".

Examples of publicly visible interfaces that are unstable
(i.e. not-an-interface): GUI, CLIs whose output format will change

Deprecated

APIs that could potentially be removed in the future and should not be used.

How are the Classifications Recorded

How should the classification be recorded for the annotated APIs?

FAQ