Release Checklist

From K-3D

Requirements

• Provide a consistent, predictable release mechanism for downstream distributors.
• Ensure that all files for a given release share the exact same codebase.
• Utilitize consistent naming and terminology to avoid confusion.

Terminology

See Version Numbers to understand the K-3D version numbering system. Note that the four-digit K-3D version number is the only mechanism for identifying versions, do not add additional qualifiers to the release such as "beta", "rc2", etc. Rationale: four levels of granularity is already overkill, and additional qualifiers cause problems for downstream distributors.

A "release" is a snapshot of the software at a moment in time. A subsequent build at a different moment in time is a different release.

A "stable" release is a release that's based on a specific Subversion branch that has been designated a "stable branch". In order to qualify as a stable release, it must include all supported distributables - at the time of this writing, source tarballs, Win32 binary installer, and OSX bundle. If it doesn't include everything (e.g: the Win32 build isn't working, so you didn't build it), then it isn't a stable release! Note that the scope of changes to a stable branch are limited to bug-fixes and low-risk features. Rationale: we want the term "stable" to be meaningful and based on observable facts, not just someone's opinion.

A "build" is a release with a different build number - as explained in Version Numbers, the build number is used to identify changes to the software that address a single platform-specific build, installation, or distribution issue.

Checklist

Development Releases

• Notify mailing list of the pending release, to avoid last-minute checkins.
• Verify that your source tree is in-sync with the subversion repository:

$ cd k3d
$ svn update && svn status

• Ensure that the top-level CMakeLists.txt has the correct release version. If not, commit the correct version to subversion.
• From the build directory, re-run cmake, e.g:

$ cd k3d-build
$ cmake .

• Tag the source tree:

$ make tag-trunk

• Create the source tarball:

$ make package_source

• Upload the source tarball to SourceForge.
  • All releases are named "K-3D <version>", e.g. "K-3D 0.5.10.1" or "K-3D 0.7.6.0"
  • The release notes should contain a high-level description of the release, and will be the identical for a given minor release.
  • The release changes should contain all of the changes from the previous release.
• On Win32, build the binary installers:

$ cd k3d-build
$ make package

• Upload the binary installers to SourceForge.
  • Ensure that the release name, notes, and changes exactly match those from the source release.
• Bump CMakeLists.txt to the next version, and commit it to subversion. Rationale: to prevent confusion between the released software and the code in subversion.
• Run "make changelog" to create a ChangeLog in the build directory, synchronized with subversion.
• Notify mailing list that the release is ready, developers can resume normal checkins.
• Update the latest development version template at Template:Latest_Development_Version_Number

Dealing With Problems

• A major bug is discovered immediately following a release. The temptation in this case is to quickly fix it and upload an updated tarball. You must resist this tempation! Cutting corners in this area causes needless confusion by releasing multiple tarballs and/or binaries into the wild, with identical version numbers. Remember that a release is just "a snapshot in time" ... fix the problem, and create another release with a new version number.
• The sources have been tagged, and everybody thought the Win32 build was up-to-date, but a problem is discovered at the last moment. In this case, developers work together to commit necessary changes to CVS and re-tag the sources. The updated tarball is created and uploaded to SourceForge, and the Win32 build process continues where it left off.