Creating Commons Package Releases

Delivered-To: mailing list commons-dev@jakarta.apache.org Received: (qmail 48983 invoked by uid 500); 14 Mar 2004 18:47:40 -0000 Received: (qmail 48962 invoked from network); 14 Mar 2004 18:47:39 -0000 Received: from unknown (HELO minotaur.apache.org) (209.237.227.194) by daedalus.apache.org with SMTP; 14 Mar 2004 18:47:39 -0000 Received: (qmail 65312 invoked by uid 1340); 14 Mar 2004 18:47:47 -0000 Date: 14 Mar 2004 18:47:47 -0000 Message-ID: <20040314184747.65311.qmail@minotaur.apache.org> From: dirkv@apache.org To: jakarta-commons-cvs@apache.org Subject: cvs commit: jakarta-commons/commons-build/xdocs/releases releases.xml versioning.xml index.xml X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N dirkv 2004/03/14 10:47:47 Modified: commons-build/xdocs/releases index.xml Added: commons-build/xdocs/releases releases.xml versioning.xml Log: move into releases directory Revision Changes Path 1.4 +3 -1 jakarta-commons/commons-build/xdocs/releases/index.xml Index: index.xml =================================================================== RCS file: /home/cvs/jakarta-commons/commons-build/xdocs/releases/index.xml,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- index.xml 1 Mar 2004 22:31:34 -0000 1.3 +++ index.xml 14 Mar 2004 18:47:47 -0000 1.4 @@ -45,10 +45,12 @@

1.1 jakarta-commons/commons-build/xdocs/releases/releases.xml Index: releases.xml =================================================================== Creating Commons Package Releases Commons Documentation Team

This document is now deprecated since it describes how to create an unmirrored release. Mirroring releases makes downloads quicker for users and saves bandwidth for Apache. So please, mirror all new releases!

The new documentation can be found here.

The Jakarta Commons project differs from many other Jakarta hosted projects because it is comprised of multiple, independently released packages. Therefore, the release procedure for an individual package needs to be documented so that package authors follow consistent practices.

Individual packages (such as Collections) might vary from these practices because they are somewhat larger than the typical Commons package, but these steps should prove sufficient for the majority of cases.

The following steps are required to create and deploy a release version of a Commons library package. The example text consistently assumes that we are releasing version 1.2 of the foo package.

For components other than Collections:

Announce your proposed release of a particular package to the commons-dev@jakarta.apache.org mailing list, and ask for a vote. Per the Commons Project charter, votes of committers on the particular package in question (as listed in the STATUS.html file) are binding.
Log on to jakarta.apache.org (via SSH) and create a new subdirectory for the release you are about to create. For example:
```
  cd /www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/
  mkdir v1.2
  
  
```
Please make sure that the directory you create is group writable.
Check out and thoroughly test the package code that you plan to release.
Update the project version number in the build.xml file for this project. If the foo project follows the usual build.xml conventions, there will be an Ant property named component.version that would be updated to 1.2. Check in any files you have modified.
Tag only the files in the subdirectory for this package with the package name (in caps) and version number for the package you are creating. For example,
```
  cd $JAKARTA_COMMONS_HOME/foo
  cvs tag FOO_1_2
  
```
Regenerate the binary distribution of the code by running the dist target. Review the generated documentation to ensure that it correctly reflects the functionality (and the version number) of this code.

Based on the contents of the dist subdirectory that was created by the previous step, create the binary distributions for this release. For example,

  cd $JAKARTA_COMMONS_HOME/foo
  mv dist commons-foo-1.2
  tar zcvf commons-foo-1.2.tar.gz commons-foo-1.2
  zip -r commons-foo-1.2.zip commons-foo-1.2
  mv commons-foo-1.2 dist

Upload the binary distribution files to the newly created directory on daedalus. For example (where "xyz" is your login),
```
  cd $JAKARTA_COMMONS_HOME/foo
  scp commons-foo-1.2.* \
   xyz@jakarta.apache.org:/www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/v1.2/
  
```
Please make sure that the files you copy are group writable.

Log in to cvs.apache.org and create the source distributions, based on the tag specified earlier, and move these files to the distribution directory as well. For example (where "xyz" is your login),

  mkdir temp
  cd temp
  cvs -d /home/cvspublic export -r FOO_1_2 jakarta-commons
  mv jakarta-commons commons-foo-1.2-src
  tar zcvf commons-foo-1.2-src.tar.gz commons-foo-1.2-src
  zip -r commons-foo-1.2-src.zip commons-foo-1.2-src
  rm -rf commons-foo-1.2-src
  scp commons-foo-1.2-src.* \
    xyz@jakarta.apache.org:/www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/v1.2/

Please make sure that the files you copy are group writable.

Follow standard procedures to update the Jakarta web site (stored in CVS repository jakarta-site2 to reflect the availability of the new release. Generally, you will be updating the following pages:
- xdocs/site/binindex.xml - Create a link to the release directory under the Release Builds heading.
- xdocs/site/sourceindex.xml - Create a link to the release directory under the Release Builds heading.
- xdocs/site/news.xml - Create a news item that describes the new release, and includes hyperlinks to the release directory.
- Then run ant at the base to generate the new docs and commit the changes to jakarta-site2.
```
  ant
  cvs commit -m "update to reflect release of commons-foo"
  
```
- If you have an account on daedalus, log in and update the web site:
```
  cd /www/jakarta.apache.org
  cvs update index.html site
  
```
- You can also update the API docs and Release notes link:
```
  cd /www/jakarta.apache.org/commons/foo
  rm RELEASE-NOTES.txt
  rm api
  rm -rf commons-foo-1.1
  tar zxf ../../builds/jakarta-commons/release/commons-foo/v1.2/commons-foo-1.2.tar.gz
  ln -s commons-foo-1.2/RELEASE-NOTES.txt RELEASE-NOTES.txt
  ln -s commons-foo-1.2/docs/api api
  
```
Update the pertinent documents in the jakarta-commons/xdocs CVS and then build the docs by running ant. These pages will probably include components.xml and foo.xml. CVS commit, then if you have an account on daedalus, update the commons website with a cvs udpate in /www/jakarta.apache.org/commons.
Announce the availability of the new package on (at least) the following mailing lists:
- announcements@jakarta.apache.org
- commons-dev@jakarta.apache.org
- commons-user@jakarta.apache.org
Ensure that the pertinent documents in the component's home directory are updated to reflect the new release. In particular :
- In STATUS.html:
  - Update Release Info section
  - Ensure Dependencies is correct
  - Ensure completed tasks are removed from To Do list
- Update build with new current version
Check in bugzilla for all bugs which have been marked LATER and update their status appropriately. If you need to have some changes made to bugzilla you can contact mvdb@apache.org

For Collections:

Follow steps 1-5 above.
Review the build.xml file to make sure that the "cvs.tag" property is set correctly. For example,
```
  <property name="cvs.tag" value="FOO_1_2"/>
```
Review the build.properties file to make sure that the "cvs.root" property is set correctly. For example,
```
  ## in build.properties where "xyz" is your login
  cvs.root=:pserver:xyz@localhost:/home/cvs
  
```
From the component directory, run ant clean dist dist-src.

Upload the binary distribution files to the newly created directory on daedalus. For example (where "xyz" is your login),

  cd $JAKARTA_COMMONS_HOME/foo/dist
  scp commons-foo-1.2* \
   xyz@jakarta.apache.org:/www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/v1.2/

Copy the release notes to daedalus. For example (where "xyz" is your login),

  cd $JAKARTA_COMMONS_HOME/foo/dist
  scp RELEASE-NOTES-1.2.html \
   xyz@jakarta.apache.org:/www/jakarta.apache.org/builds/jakarta-commons/release/commons-foo/v1.2/

Update the components.xml and the collections.xml (including the link to the STATUS.html) files. Run the ant command at the root of the jakarta-commons module, which will build HTML versions of those documents in the docs directory. Check in the generated docs.
Copy the API docs from the Collections build to the jakarta-commons/docs/collections/api directory in CVS. Be sure to remove Javadocs for any Collections that have been permanently deleted.
Log onto jakarta.apache.org and perform a CVS update to grab the new site documentation:
```
  cd /www/jakarta.apache.org/commons/
  cvs update
  
```
Follow steps 10+ above.

1.1 jakarta-commons/commons-build/xdocs/releases/versioning.xml Index: versioning.xml =================================================================== Versioning Guidelines Commons Documentation Team Morgan Delagrange Rodney Waldhoff

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,
and a protocol for communicating those changes and incompatibilities to users and developers.

We identify three distinct categories of interfaces or APIs within a component: external, internal and private.

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 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 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.

Whenever a class, interface or member is considered part of the external or internal interface of a component, it should be clearly indicated as such in the JavaDoc comments or other documentation for the component. (We may want to consider adding custom JavaDoc tags for this purpose.)

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.

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 behaviour-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.

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 behaviour 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.

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 behaviour 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.

We identify five types of releases: "Major", "Minor", "Point", "Beta" and "Milestone".

Developers are encouraged to "upgrade" a release to a stronger type whenever the nature or scope of the change warrants it.

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 the previous release.

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.

In other words, whenever a client depends upon at most the external interface of a component with a given minor release, it will work with all subsequent minor releases within that major release.

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.

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.

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.

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

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 releases are denoted by adding "B<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-B1.

Beta 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.

We identify four possible states: "in development", "beta", "released", and "unsupported".

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.

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.

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.

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.

Using this approach it is possible to very precisely and concisely define the dependencies between a component and its clients.

For example, suppose that the application Foo depends (only) upon features of the commons-superwidget component that are part of the external interface in release 2.3.0. Then the maintainers of Foo can state with a high degree of certainty that Foo will work with any 2.x release of superwidget (x >= 3).

Similarly, suppose the application Bar depends upon features of superwidget that were part of the internal 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 re-evaluate.

Note 1: We say "nearly" here since there are rare or unusual circumstances in which changes that are usually "safe" may cause problems for a small number of users. For example, adding a new method to a component class shouldn't in general cause problems for any clients. But it may cause problems for some clients who've extended that class and already added a method with the same signature in their subclass.

--------------------------------------------------------------------- To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org For additional commands, e-mail: commons-dev-help@jakarta.apache.org