The External Interface

The external interface of component is composed of the public-facing classes, interfaces, methods and attributes provided by the component--those that are likely to be used by clients to the component.

For obvious reasons, we try to avoid or at least acknowledge changes to the external interface.

The external interface of a component may correspond to the public scope classes and members, but this is not always the case. For example, a protected method of a class designed to be extended by the clients of a component may be deemed part of the external interface.

The Internal Interface

The internal interface of a component is composed of the classes, methods and attributes that are primarily or exclusively intended for use by the component implementation itself. Clients to the component are unlikely to use or be concerned with the internal interface.

The internal interface of a component may correspond to the package and private scope classes and members of the component, but this is not always the case. For example, a component implementation may be split over multiple packages and hence require protected scope members, or may, for design reasons, include an interface intended primarily for internal use.

The Private Interface

The private interface of a component is just that--the set of classes, methods and attributes that have "package" or private scope and hence cannot be used by external clients by virtue of the Java Language Specification.

Fully-Compatible Changes

Release B is said to be fully-compatible with Release A if B can simply replace A in (nearly) all circumstances and deployments without changing the client code or configuration, and without changing the semantics of any public or protected member.

Examples of fully-compatible changes include:

• adding a non-abstract method to a class
• adding a class or interface to a component
• changing a member from private to protected
• changing a private attribute to a private method
• changing an implementation such that a given external library is no longer needed by the component
• changing a method or class from final to non-final
• deprecating, but not otherwise changing, a class, inteface or member
• changing a component in order to fix a defect (a deviation from the documented or reasonably expected behavior), assuming no other incompatibilities are introduced

Examples of changes which are not fully-compatible include:

• a release that no longer supports the same set of JREs, or that requires new libraries to be added to the classpath
• changing a public or protected method signature
• changing the default value of an attribute in a behavior-impacting way
• removing a class, interface, method or attribute from either the internal or external interface of the component

Note that not every non-fully-compatible change will cause compilation or readily apparent run-time problems.

Generally speaking, a fully-compatible change will at most change the private interface of a component, or simply add classes, methods and attributes whose use is optional to both internal and external interface clients.

Interface-Compatible Changes

Release B is said to be "interface-compatible" with Release A if (nearly) all clients that can be compiled with A in the classpath can also be compiled with B in the classpath, without changing the semantics of any public or protected member. A configuration or classpath change may be required.

Examples of interface-compatible changes include:

• all fully-compatible changes
• changing a component such that it now depends upon an additional external library or configuration file

Examples of changes which are not interface-compatible include:

• changing a public or protected method signature
• changing the default value of an attribute in a behavior changing way
• removing a class, interface, method or attribute from either the internal or external interface of the component

Generally speaking, an interface-compatible change will at most change the private interface of a component, or simply add classes, methods and attributes whose use is optional to both internal and external interface clients.

External-Interface-Compatible Changes

Release B is said to be "external-interface-compatible" with Release A if (nearly) all clients that depend only on the external interface of a component and that can be compiled with A in the classpath can also be compiled with B in the classpath, without changing the semantics of any member in the external interface. A configuration or classpath change may be required.

Examples of external-interface-compatible changes include:

• all interface-compatible changes
• removing a class, interface, method or attribute from the internal interface of the component
• a change to the internal or private interface of a component that requires a change in configuration settings or in the external libraries required to use the component
• changes to the internal or private interface of a component without impacting the external interface

Examples of changes which are not external-interface-compatible include:

• changing the method signature of any method that is part of the external interface of the component
• changing the default value of any attribute that is part of the external interface of the component in a behavior changing way
• removing a class, interface, method or attribute from external interface of the component

Generally speaking, external-interface-compatible changes correspond to changes to at most the internal interface of the component or the addition of optional classes, interfaces or members to the external interface.

Major Releases

Major releases signify significant changes to a component. Developers may perform a major release if there have been substantial improvements to the component. Developers must perform a major release whenever the new release is not at least interface-compatible with the previous release.

Minor Releases

Minor releases signify enhancements to a component that do not necessitate a major release. Developers may perform a minor release if the release is at least external-interface-compatible with the previous release.

Point Releases

A point release typically involves simple bug fixes or optimizations that do not introduce new features. Developers may perform a point release if the release is at least interface-compatible with the previous release.

In other words, whenever a client depends upon a component with a given point release, it will work with all subsequent point releases within that minor release.

Beta Releases

Developers may, at their option, perform a beta preview of any major, minor or point release. Beta releases may be performed for a variety of purposes such as:

• Showcasing new, untested features
• Providing early corrections of critical bugs
• Generating a stable version before large-scale changes

While every effort should be made to ensure the quality of released code, "beta" releases are essentially provided as-is with no guarantees of stability or maintenance.

Milestone Releases

Developers may, at their option, offer a milestone preview of any major release. A milestone release is appropriate when part of the overall component is fully functioning and the team wants to make it more widely available for testing. Those features implemented and those remaining to be implemented should be clearly defined and documented.

While every effort should be made to ensure the quality of released code, "milestone" releases are essentially provided as-is with no guarantees of stability or maintenance.

Initial Release Number

A component's initial release number is generally 1.0[.0], unless there have been versioned beta releases.

Dissecting the Release Number

A release number is comprised of 3 components: the major release number, the minor release number, and an optional point release number. Here is a sample release number:

2.0.4

and it can be broken into three parts:

• major release: 2
• minor release: 0
• point release: 4

The next release of this component would increment the appropriate part of the release number, depending on the type of release (major, minor, or point). For example, a subsequent minor release would be version 2.1, or a subsequent major release would be 3.0.

Note that release numbers are composed of three _integers_, not three digits. Hence if the current release is 3.9.4, the next minor release is 3.10.0.

Beta Release Numbers

Beta releases are denoted by adding "beta<beta version number>" after the release number. For example, if the current release version is 2.0.4, and a developer wished to preview the next major release, the release would be labeled 3.0-beta1.

Milestone Release Numbers

Milestone releases are denoted by adding "M<milestone version number>" after the release number. For example, if the current release version is 2.0.4, and a developer wished to preview the next major release, the release would be labeled 3.0-M1.

In Development State

When a component is "in development", it is new and still relatively unstable. Typically components in this state do not have any binary releases available beyond the nightly builds. Users should be made aware that this component may change its functionality or interface before a stable release is achieved. A "milestone" release may be made while the component is still "in development" to make the features currently implemented more widely available for testing in a more stable test version.

Beta State

When a component has made significant progress toward release-quality code, the committers may vote to perform a "beta" release. At this point, the component state will change from "in development" to "beta". The component will remain in this state until it is ready for its first major release.

Note that developers may skip vote to skip the "beta" state and go directly to "released", if the component is sufficiently stable.

Released State

When a new component is finally production-quality, the developers may vote to perform the first major release. At this point, the component status will be changed from "beta" to "released". In the future this component will always be considered to be in the "released" state, even when new releases are initiated. The only exception is in the case of "unsupported" components.

Unsupported State

Under rare circumstances, committers may vote to make a component "unsupported", if there are no resources to maintain the library or if it has been completely supplanted by another component. Only "released" components may become "unsupported"; components in other states will simply be terminated after a brief warning period.