HOWTO-RELEASE ============= TABLE OF CONTENTS ----------------- 1 RELEASE TYPES 1.1 "MAJOR" RELEASE 1.2 "MINOR" RELEASE 1.3 "BUG FIX" RELEASE 1.4 "BETA" RELEASES 1.5 "MILESTONE" RELEASES 2 RELEASE NUMBERS 2.1 INITIAL RELEASE NUMBER 2.2 DISCECTING THE RELEASE NUMBER 2.3 "BETA" RELEASE NUMBERS 2.4 "MILESTONE" RELEASE NUMBERS 3 STARTING/COMPLETING MAJOR RELEASES 4 DEVELOPMENT STATES 4.1 "IN DEVELOPMENT" STATE 4.2 "BETA" STATE 4.3 "RELEASED" STATE 4.4 "UNSUPPORTED" STATE 5 NEWS 5.1 UPDATING THE NEWS 6 CVS REPOSITORIES 6.1 MAIN REPOSITORY 6.2 SANDBOX REPOSITORY CONTENTS -------- 1 RELEASE TYPES There are four types of releases: "Major", "Minor", "Bug Fix", and "Beta". See also Section 2, which describes how releases are numbered. 1.1 "MAJOR" RELEASE Major releases signify signifant changes to a tag library. Developers _may_ perform a major release if there have been substantial improvements to the tag library. Developers _must_ perform a major release if there is _any_ non-backwards compatible change to a tag interface. 1.2 "MINOR" RELEASE Minor releases signify enhancements to a tag library that do not necessitate a major release. If the developers change the tag library interfaces in a non-backwards compatible way, those changes _cannot_ be bundled in a minor release; a major release _must be performed_. 1.3 "BUG FIX" RELEASES A bug fix release involves simple bug fixes that do not introduce new features. Developers are not required to perform bug fix releases if they can address the bug in a minor release. Developers are _strongly encouraged_ but not required to perform bug fix releases on previous major releases if a bug in that release is uncovered. 1.4 "BETA" RELEASES Developers may, at their option, perform a beta preview of any major, minor or bug fix 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 Developers should attempt to describe the purpose behind the beta release in the "News" section of the site (see section 5 for details). 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. 1.5 "MILESTONE" RELEASES Developers may, at their option, perform a milestone preview of any major release. A milestone release is when you have part of the overall taglib fully functioning and you want to make it more widely available for testing. Those features implemented and those remaining to be implemented should be clearly defined and documented. Developers should attempt to describe the purpose behind the milestone release in the "News" section of the site (see section 5 for details). 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. 2 RELEASE NUMBERS 2.1 INITIAL RELEASE NUMBER A tag library's initial release number is generally 1.0, unless there have been versioned beta releases. 2.2 DISCECTING THE RELEASE NUMBER A release number is comprised of 2-3 components: the major release number, the minor release number, and an optional bug fix 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 bug fix release # = 4 The next release of this tag library would increment the appropriate part of the release number, depending on the type of release (major, minor, or bug fix). For example, a subsequent minor release would be version 2.1, or a subsequent major release would be 3.0. 2.3 "BETA" RELEASE NUMBERS Beta releases are denoted by adding "B" after the release number in the released archive. For example, if the current release version is 2.0.4, and the developer wished to preview the next major release, the jar would be named foo-3.0-B1.jar. 2.4 "MILESTONE" RELEASE NUMBERS Milestone releases are denoted by adding "M" after the release number in the released archive. For example, if the current release version is 2.0, and the developer wished to preview the next major release, the jar would be named foo-3.0-M1.jar. 3 STARTING/COMPLETING MAJOR RELEASES (See section 1.1 for the definition of a "Major" release.) Let's assume that the current release of your tag library is 2.0.4, but you want to start work on 3.0. Here are the steps you would take to start working on the new release: 1) Make an announcement on taglibs-dev 2) Create a branch called rel2 in CVS for the entire tag library, which will preserve the currently released version 3) Continue work for the 3.0 release on the MAIN branch Once the 3.0 version is ready for release to the public, you would do this: 1) Call a release vote on taglibs-dev 2) After receiving approval, build the release jar and place it on the site The version 3 release is the main trunk of the CVS tree. However, versions 2 and 1 will still be available on other branches (rel2 and rel1), if other releases of that version prove necessary. 4 DEVELOPMENT STATES Each tag library also has its development state listed on the main website. There are four possible states: "in development", "beta", "released", and "unsupported". 4.1 "IN DEVELOPMENT" STATE When a tag library is "in development", it is new and still relatively unstable. Typically tag libraries in this state do not have any binary releases available beyond the nightly builds. Users should be made aware that this tag library may change its functionality before a stable release is achieved. A "milestone" release may be made while the tag library is still "in development" to make the features currently implemented more widely available for testing in a more stable test version. 4.2 "BETA" STATE When a tag library 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 tag libraries state will change from "in development" to "beta". The tag library 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 tag library is sufficiently stable. 4.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 tag libraries status will be changed from "beta" to "released". In the future this tag library will always be considered to be in the "released" state, even when new releases are begun (section 3). The only exception is in the case of "unsupported" tags. 4.4 "UNSUPPORTED" STATE Under rare circumstances, the Taglibs committers may vote to make a tag library "unsupported", if there are no resources to maintain the library or if it has been completely supplanted by a superior tag library. Only "released" tags may become "unsupported"; tags in other states will simply be terminated after a brief warning period. 5 NEWS There is a "news" section of the Jakarta taglibs site. This portion of the site provides a notification of each major, minor or bug fix release of each tag library. Each release notification will link to the "news" section for that tag library, which will contain the details of what new features were introduced, which bugs were fixed, etc. 5.1 UPDATING THE NEWS Documentation for the http://jakarta.apache.org/taglibs site and the main documentation page for individual tag libraries are updated automatically by the nightly build process. 6 CVS REPOSITORIES 6.1 MAIN REPOSITORY The main repository for Jakarta taglibs is located in the jakarta-taglibs module. Refer to the Jakarta site documentation for how to access a Jakarta CVS repository. The main repository contains approved tag libraries that are being developed by the Taglibs project committers. 6.2 SANDBOX REPOSITORY Jakarta taglibs also has a "sandbox" repository located in the jakarta-taglibs-sandbox module. The sandbox is intended to be a place for experimenting with new tags or submitting tentative tag library proposals. Jakarta committers from any project may request access to the sandbox in order to submit their ideas. If a tag library in the sandbox recieves a majority vote from the Taglibs committers it is moved into the main repository. Users may download and use tag libraries in the sandbox, but those libraries are presented AS IS with no guarantees for stability or longevity. 6.3 COMMIT PRIVILEDGES Those taglib developers granted commit priviledges to the jakarta-taglibs repository are automatically granted priviledges to the jakarta-taglibs-sandbox repository, and vice versa.