cvs commit: jakarta-commons VERSIONING-GUIDELINES.txt
rwaldhoff01/08/30 11:29:37 Added: .VERSIONING-GUIDELINES.txt Log: initial draft Revision ChangesPath 1.1 jakarta-commons/VERSIONING-GUIDELINES.txt Index: VERSIONING-GUIDELINES.txt === $Id: VERSIONING-GUIDELINES.txt,v 1.1 2001/08/30 18:29:37 rwaldhoff Exp $ --- This is a draft set of recommendations, adapted from a similar document in the Jakarta-Taglibs project. It is not binding in any way, although Jakarta-Commons components may choose to adhere to these guidelines. --- VERSIONING GUIDELINES - TABLE OF CONTENTS - 1 OVERVIEW 2 TYPES OF INTERFACE 2.1 EXTERNAL INTERFACE 2.2 INTERNAL INTERFACE 2.3 PRIVATE INTERFACE 3 TYPES OF CHANGE 3.1 FULLY-COMPATIBLE CHANGES 3.2 INTERFACE-COMPATIBLE CHANGES 3.3 EXTERNAL-INTERFACE-COMPATIBLE CHANGES 3.4 INCOMPATIBLE CHANGES 4 RELEASE TYPES 4.1 MAJOR RELEASES 4.2 MINOR RELEASES 4.3 POINT RELEASES 4.4 BETA RELEASES 4.5 MILESTONE RELEASES 5 RELEASE NUMBERS 5.1 INITIAL RELEASE NUMBER 5.2 DISSECTING THE RELEASE NUMBER 5.3 BETA RELEASE NUMBERS 5.4 MILESTONE RELEASE NUMBERS 6 DEVELOPMENT STATES 6.1 IN DEVELOPMENT STATE 6.2 BETA STATE 6.3 RELEASED STATE 6.4 UNSUPPORTED STATE 7 COMMENTARY CONTENTS 1 OVERVIEW This document provides: * a set of guidelines intended to help the Jakarta-Commons team balance the need to provide a stable interface to clients with the growth and evolution of components over time * a language for describing the changes to a component and the types of incompatibilities such changes may create * a protocol for communicating those changes and incompatibilities to users and developers. 2 INTERFACE TYPES We identify two distinct categories of interfaces or APIs within a component: external and internal. 2.1 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 of a component. 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. If a class, interface or member is considered part of the external interface of the component, it should be clearly indicated as such in the JavaDoc comments or other documentation for the component. (We may want to consider adding a custom JavaDoc tag for this purpose.) 2.2 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. If a class, interface or member is considered part of the internal interface of the component, it should be clearly indicated as such in the JavaDoc comments or other documentation for the component. (We may want to consider adding a custom JavaDoc tag for this purpose.) 2.3 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. 3 TYPES OF CHANGE We can categorize the changes to a component according to the degree to which these changes are compatible with previous releases of the component. We define three such categories: fully-compatible, interface-compatible, and external-interface-compatible. 3.1 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
cvs commit: jakarta-commons VERSIONING-GUIDELINES.txt
rwaldhoff01/08/30 14:58:39 Modified:.VERSIONING-GUIDELINES.txt Log: minor corrections Revision ChangesPath 1.2 +13 -15jakarta-commons/VERSIONING-GUIDELINES.txt Index: VERSIONING-GUIDELINES.txt === RCS file: /home/cvs/jakarta-commons/VERSIONING-GUIDELINES.txt,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- VERSIONING-GUIDELINES.txt 2001/08/30 18:29:37 1.1 +++ VERSIONING-GUIDELINES.txt 2001/08/30 21:58:39 1.2 @@ -1,4 +1,4 @@ -$Id: VERSIONING-GUIDELINES.txt,v 1.1 2001/08/30 18:29:37 rwaldhoff Exp $ +$Id: VERSIONING-GUIDELINES.txt,v 1.2 2001/08/30 21:58:39 rwaldhoff Exp $ --- This is a draft set of recommendations, adapted from a similar document in the Jakarta-Taglibs project. It is not @@ -22,7 +22,6 @@ 3.1 FULLY-COMPATIBLE CHANGES 3.2 INTERFACE-COMPATIBLE CHANGES 3.3 EXTERNAL-INTERFACE-COMPATIBLE CHANGES -3.4 INCOMPATIBLE CHANGES 4 RELEASE TYPES 4.1 MAJOR RELEASES @@ -242,7 +241,7 @@ 4 RELEASE TYPES We identify five types of releases: Major, Minor, -Point, and Beta. +Point, Beta and Milestone. Developers are encouraged to upgrade a release to a stronger type whenever the nature or scope of the change @@ -377,10 +376,10 @@ When a component has made significant progress toward release-quality code, the committers may vote to perform -a beta release (see section 1.4). 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. +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 @@ -389,13 +388,12 @@ 6.3 RELEASED STATE When a new tag library is finally production-quality, the -developers will vote to perform the first major release -(see section 1.1). 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 initiate. -The only exception is in the case of unsupported -components. +developers will 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. 6.4 UNSUPPORTED STATE @@ -425,5 +423,5 @@ interface of release 2.3.0. Then the maintainers of Bar can state with a high degree of certainty that Bar will work with any 2.3.x release of superwidget. Only once 2.4 -(or 3.0) is released, will Bar's developers have to +(or 3.0) is released will Bar's developers have to re-evaluate.
