Legacy 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. In order to qualify as a release, it must include all supported distributables - at the time of this writing, source tarballs and Win32 binary installers. 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 release!

A "stable" release is a release that's based on a specific CVS branch that has been designated a "stable branch". 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, 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

1. Notify mailing list of the pending release, to avoid last-minute checkins.
2. Use the mailing list to confirm that the Win32 build is synchronized and intact.
3. Checkout a new copy of the repository, into an empty directory.
4. Ensure that configure.ac has the correct release version. If not, commit the correct version to CVS.
5. Run "./bootstrap && ./configure".
6. Run "make trunk-changelog" to synchronize the ChangeLog with CVS, and commit it to CVS. The commit message should contain the version about to be released, e.g. "COMP: K-3D 0.7.6.0"
7. Run "make tag" to tag the source tree.
8. Run "make release" to create the source tarball.
9. 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.
10. Retrieve and unpack release tarball from SourceForge.
11. Run "make -f Makefile.codeblocks" to configure the sources.
12. Build using code::blocks.
13. Run "make -f Makefile.codeblocks installers" to build the binary installers.
14. Upload the binary installers to SourceForge.
    • Ensure that the release name, notes, and changes exactly match those from the source release.
15. Bump configure.ac to the next version, and commit it to CVS. Rationale: to prevent confusion between the released software and the code in CVS.
16. Notify mailing list that the release is ready, developers can resume normal checkins.

Stable Releases

1. Notify mailing list of the pending release, to avoid last-minute checkins.
2. Use the mailing list to confirm that the Win32 build is synchronized and intact.
3. Checkout a new copy of the repository, into an empty directory.
4. Ensure that configure.ac has the correct release version. If not, commit the correct version to CVS.
5. Run "./bootstrap && ./configure".
6. Run "make release-changelog" to synchronize the ChangeLog with CVS, and commit it to CVS. The commit message should contain the version about to be released, e.g. "K-3D 0.8.2.1"
7. Run "make tag" to tag the source tree.
8. Run "make release" to create the source tarball.
9. Upload the source tarball to SourceForge.
   • All stable releases are named "K-3D <version> (Stable)", e.g. "K-3D 0.6.1.0 (Stable)" or "K-3D 0.8.2.1 (Stable)"
   • 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.
10. Retrieve and unpack release tarball from SourceForge.
11. Run "make -f Makefile.codeblocks" to configure the sources.
12. Build using code::blocks.
13. Run "make -f Makefile.codeblocks installers" to build the binary installers.
14. Upload the binary installers to SourceForge.
    • Ensure that the release name, notes, and changes exactly match those from the source release.
15. Bump configure.ac to the next version, and commit it to CVS. Rationale: to prevent confusion between the released software and the code in CVS.
16. Notify mailing list that the release is ready, developers can resume normal checkins.
17. Merge changes in the stable release branch back to the trunk of the source tree.

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.