Chapter 17. Project Release Procedures
Prev   Next

Chapter 17. Project Release Procedures

This section describes the JBoss Project Release procedure.

17.1. Tagging Standards

Tags on JBoss projects should consist of two parts - project identifier and version number. A list of existing modules can be found on the CVS Modules page. The version number must follow JBoss Versioning Conventions . A correctly tagged project would be JBoss_4_0_2, which is the tag for the JBoss Application Server, version 4.0.2. Note that all '.' from the version have been replaced with '_'.

17.2. JBoss Versioning Conventions

Product versions follow this format X.YY.ZZ.Q* (i.e. 1.2.3.GA, 1.2.3.CR1, 1.2.3.Alpha1-20060205091502)

  • X signifies major version related to production release.
  • YY signifies minor version with minor feature changes or additions (use of even numbers is preferred - 3.0, 3.2, 3.4, etc.).
  • ZZ signifies patches and bug fixes. Minor features that do not introduce backward compatibility issues are ok.
  • Q* is an alpha-numeric qualifier. The prefix of the qualifier needs to match the qualifier conventions listed below to ensure that versions can be compared consistently in terms of version ordering.

Major versions are usually developed in multiple iterations. Each iteration concludes with an intermediate version release. Intermediate versions are annotated with appropriate suffixes. This shows the progression of release versions. A given release may not have all stages of releases shown here.

17.2.1.  Current Qualifier Conventions (Post 2006-03-01)

The following version conventions were put in place to have interop with eclipse/OSGI bundle version conventions.

  1. X.Y.ZZ.Alpha# - An Alpha release includes all key features and is passing the main test cases. It still needs work on edge cases, bug fixes, performance tuning and other optimization tasks.
  2. X.Y.ZZ.Beta# - A Beta release is the first release that the development and QA teams feel comfortable releasing for public testing. Some bug fixes and minor optimizations are expected, but no significant refactoring should occur. No new major features are introduced from this phase on. Only stabilizing work.
  3. X.Y.ZZ.CR# - Each candidate for release is a potential target for final release. Only if unexpected bugs are reported during the iteration timeframe the CR number is incremented (e.g. jboss-4.0.1.CR1 to jboss-4.0.1.CR2) and another release candidate is published. Generally only minor bug fixes are introduced to code and documentation.
  4. X.Y.ZZ.GA - A Final version is released when there are no outstanding issues from the last CR version. Usually it's a matter of renaming the version from CR# to Final and repackaging the software.
  5. X.Y.ZZ.SP# - A service pack release to a final release. A service pack may be made when there are significant issues found after a final release to provide a bug fix release before the next scheduled final release.

17.2.2. Practices

The standard qualifiers are the required prefixes. Additional information may be included in the qualifer as a suffix to incorprate information such as the build id to allow for distinction between nightly builds for example. If a given branch of a project is at 1.2.3.Beta1, the full version used could include a build id based on a GMT timestamp, the actual number of builds, etc. using a full qualifier syntax like Beta1-NNN where NNN is the numeric build id.

The key thing is that all version usage be consistent for a given project. A project cannot include a build id in the nightly builds, and then fail to include a build id of greater value when 1.2.3.Beta1 is actually released. The reason is that 1.2.3.Beta1 cannot be seen to be older than some previous 1.2.3.Beta1-NNN nightly build.

17.2.3. Legacy Qualifier Conventions (Pre 2006-03-01)

  1. X.Y.ZZ.DR# - DR stands for Development Release. There could be a number of development releases. For example jboss-4.0.0DR1. A development release is a significant project milestone, but it does not implement all of the key features targeted for the public release.
  2. X.Y.ZZ.Alpha - An Alpha release includes all key features and is passing the main test cases. It still needs work on edge cases, bug fixes, performance tuning and other optimization tasks.
  3. X.Y.ZZ.Beta - A Beta release is the first release that the development and QA teams feel comfortable releasing for public testing. Some bug fixes and minor optimizations are expected, but no significant refactoring should occur. No new major features are introduced from this phase on. Only stabilizing work.
  4. X.Y.ZZ.RC# - Each release candidate is a potential target for final release. Only if unexpected bugs are reported during the iteration timeframe the RC number is incremented (e.g. jboss-4.0.1RC1 to jboss-4.0.1RC2) and another release candidate is published. Generally only minor bug fixes are introduced to code and documentation.
  5. X.Y.ZZ.Final - A Final version is released when there are no outstanding issues from the last RC version. Usually it's a matter of renaming the version from RC# to Final and repackaging the software (jboss-4.0.1).
  6. X.Y.ZZ.SP# - A service pack release to a final release. A service pack may be made when there are significant issues found after a final release to provide a bug fix release before the next scheduled final release.

17.3. JBoss Naming Conventions

17.3.1. Naming of Build Artifacts

When creating jars as a result of a project's build, do not include the version element in the jar name. An example of that would be the current JBoss Messaging component of the Application Server - jbossmq.jar and not jbossmq-1.1.jar

17.3.2. Jar Manifest Headers

The standard Java version information and OSGI bundle version headers and their usage needs to be defined. The standard java jar manifest headers should include:

  1. Manifest-Version: 1.0
  2. Created-By: @java.vm.version@ (@java.vm.vendor@)
  3. Specification-Title: @specification.title@
  4. Specification-Version: @specification.version@
  5. Specification-Vendor: @specification.vendor@
  6. Implementation-Title: @implementation.title@
  7. Implementation-URL: @implementation.url@
  8. Implementation-Version: @implementation.version@
  9. Implementation-Vendor: @implementation.vendor@
  10. Implementation-Vendor-Id: @implementation.vendor.id@

where:

  • Specification-Title: whatever name/standard name the jar implements
  • Specification-Version: the version number
  • Specification-Vendor: JBoss ( http://www.jboss.org/ )
  • Implementation-Title: name with additional implementation details
  • Implementation-URL: http://www.jboss.org/
  • Implementation-Version: a full implementation version with addition build info. For example: ${version.major}.${version.minor}.${version.revision}.${version.tag} (build: CVSTag=${version.cvstag} date=${build.id})
  • Implementation-Vendor: JBoss Inc.
  • Implementation-Vendor-Id: http://www.jboss.org/

17.4. Pre-Release Checklist

A few tasks need to be completed before a project is handed off for release QA.

  1. The files to be released should be tagged using the correct tagging convention, and the tags should match the appropriate version, refer to Tagging Standards
  2. A roadmap which corresponds to the tag (eg. an RC1 release) should be present in JIRA, and each task in the roadmap must be marked off as completed
  3. Product version should follow Versioning Conventions
  4. The binary outputs for the project should be built and added to the repository
  5. MD5 checksums should be generated for the binary outputs of the project
  6. The testsuite should be able to run with a 100% success rate
  7. Create a JBQA issue in JIRA for coordination with QA

Once all items on the Pre-Release Checklist have been completed, the project is ready for release testing.

17.5. QA Release Process

When a project is ready for a release and the Pre-Release Checklist has been completed, the QA team follows a standard release procedure outlined below.

  1. 2 weeks prior to release the project team should open a JIRA issue in the JBoss QA project detailing what will be released, the date it is expected to be released on, and the CVS tag which will be used for the release
  2. On release day the team will tag their project appropriately and enter a comment on the JIRA issue notifying QA that the project is now ready for the QA process.
  3. QA team checks out the project and any dependent modules from cvs by the specified tag
  4. QA team then builds the project using the target distr from the build script
  5. QA team will then run the testsuite for the specific project and analyze their results - if any failures are present those issues need to be resolved by the QA or project teams before the release process could resume
  6. QA team will verify documentation is present and correct
  7. After all tests are passing, QA team will upload the disctribution archives
  8. QA team makes a release on Sourceforge.net and a binary release to jboss-head

For more detailed release process on existing JBoss Projects, refer to JBoss QA Wiki page

17.6. Release Notes

The Project Management System (JIRA) automatically generates Release Notes for a project. This is covered in Release Notes section of the JIRA chapter

Prev Up Next
Chapter 16. JBoss QA Lab Guide Home Chapter 18. Serialization