GPS Toolkit Release Process

The purpose of this document is to guide the developer though the steps required for a stable public release of the GPSTk. In order to verify the quality of the release, these steps must be followed to ensure a safe and satisfactory product. Listed immediately below is general information regarding the GPSTk stable public release. Below that, is the guide and process for a stable public release of the GPSTk.

• The GPSTk is considered released with each successive iteration of the GPSTk Subversion repository. The purpose of the stable public release is to give developers and users a verified and tested version of the GPSTk with which to work from as an alternative or in addition to the current GPSTk Subversion iteration.
• It is not realistic or efficient to expect all development on the GPSTk to be complete for any given release. Communicate with other developers to decide which additions and changes should be included and which should wait until a later stable release.
• While some of the process steps listed below imply a large amount of effort, the work required can be distributed among many developers.

Conceptually, the update process consists of the following steps:

• Determine what additions and modifications have been made – We’ll likely implement two methods of change detection for the repository. Hopefully, the CM tool will provide one method and a second (such a Tripwire) may be implemented to reduce the possibility of spoofing the CM tool. It is anticipated that the module-level confirmation hash signatures will play a role in this part of the process.
• Review additions/Modifications – All additions will be reviewed to see that they fit within the GPSTkMission. There will be a cursory review for adherence to the GPSTk CodingStandards, but this will be regarded as a matter of disallowing egregious problems (non-C/C++ submissions, use of dangerous code practices) as opposed to rigorous enforcement of the conventions. Additions will be specifically reviewed for presence of malicious code, malware, or other attempts to subvert the purpose of the library.
• Conduct regression tests – Following the reviews, the regression test suite will be run on the resulting GPSTk candidate release on all supported OS/compiler configurations. Any new regression tests provided with new additions to the library need to be reviewed and added to the test suite.
• Generate tarball – Once regression tests are completed, the GPSTk Project tarball will be generated and verified.
• Update confirmation hash signatures – Hash signatures will be generated for the final tarball and hash signatures will be updated for all components stored in the repository.

The goal is to generate updates on a regular basis (e.g. quarterly). In addition, an update may be generated whenever the GPSTk management team deems a correction is sufficiently important to warrant an immediate response. The general interaction inside and outside of ARL:UT for this process is illustrated by:

1 Release Process

1.1 Preparation for a New Release Candidate

1. The stable release schedule is maintained on the ReleaseSchedule page. One month before selecting a release candidate, the proposed iteration of the GPSTk for public release, send notice to the gpstk-devel list that a release candidate will be chosen in one month. Within the notice also ask if there is any feedback for the release candidate and if an extension of the timeline for choosing a release candidate is required before choosing the candidate.
2. Review Subversion submissions from the last stable release and generate a general list of enhancements to the source. Record these enhancements in gpstk/dev/ChangeLog.
3. Review and update gpstk/dev/INSTALL if necessary. Check to see that all files present in the directories appear in the Jamfiles/Makefiles and vice versa. Perl scripts have been written for this task: JamfileTest.pl and MakefileTest.pl .
4. Create a ReleaseNotesXX page that goes with the release. Link this on the ReleaseSchedule page.
5. Review and update gpstk/dev/AUTHORS to include recent contributors.
6. One day before selecting a release candidate, send notice to the Subversion list that a release candidate will be chosen within a day. Within the notice also ask if a timeline extension is required before choosing the candidate.

1.2 Creating a Release Candidate

1. On the day of release candidate selection, pick an appropriate release number e.g. 1.7.
2. Update gpstk/dev/NEWS with the date and version number.
3. Updated gpstk/dev/Jamfile and gpstk/dev/Makefile.am with the new release number.
4. Update gpstk/dev/ChangeLog with the activities of the last week.
5. Update the ReleaseNotesXX linked on the ReleaseSchedule page with any changes due to code changes.
6. Generate/Update a README describing the GPSTk, referencing the GPSTk website/TWiki, and a description of the files contained at a high level.
7. Generate/Update an INSTALL text file describing how to install the binaries.
8. Update the repository with the above changes.
9. Check out a fresh copy of the dev tree from the Subversion repository and take note of the revision number (r####).
10. Create a branch of the dev tree with svn copy. Call it by the Release Candidate number chosen e.g. RC1.7. This branch, though available to everyone, should only be edited and modified by those involved in the stable release process. Example svn copy https://gpstk.svn.sourceforge.net/svnroot/gpstk/dev/ https://gpstk.svn.sourceforge.net/svnroot/gpstk/RC1.7/ -m "Branching for RC1.7 from revison number r####" * It is important to include the revision number from which it was copied. It will be needed when the time comes to merge the branch back into the trunk.
11. For each supported platform, prepare a directory for platform-specific testing of the release candidate, i.e. ~/svn/osx, ~/svn/l64, etc.
12. In each prepared directory, check out a fresh copy of the branch tree (e.g. RC1.7) for use on a system which uses that platform.

1.3 Testing and Verification of the Release Candidate

1. First verify that the release candidate compiles and builds for each supported platform by checking out the release candidate and building the GPSTk using jam and then jam install, or their make equivalents. If, for any supported platform, the GPSTk does not compile and build, the release cannot continue. In order to continue with the release, fix the release candidate for each platform it did not build on, commit those changes to the branch tree of the Subversion repository, and repeat the steps starting from step 10 in 1.2 .
2. In order to look for malicious code, compare the release candidate code to a trusted code base (typically the last version of the public release). This process will generate the trusted code base for future comparisons. Typically, code is reviewed for maliciousness by members of the GPSTk Core Team. Perl scripts have been created for this purpose. If malicious code is found, alert the GPSTk project director immediately and halt the release process. In order to continue with the release process, remove the malicious code, commit those changes to the branch tree of the Subversion repository, and repeat the steps starting from step 9 in 1.2 .
3. Preform a dirty word search for ARL project related terms. Perl scripts have been created for this purpose. If any of these words are found, the release cannot continue. In order to continue with the release process, remove the offending words from the code, commit those changes to the branch tree of the Subversion repository, and repeat the steps starting from step 9 in 1.2 .
4. Run the library test suite on one system. If any of the library tests fail, the release cannot continue. In order to continue with the release process, fix the problems the library test suite encountered, commit those changes to the branch tree of the Subversion repository, and repeat the steps starting from step 9 in 1.2 .
5. If all of the above pass, contact the GPSTk project director for final approval of the Release Candidate.

1.4 Releasing the Candidate as a New Version

1. Compile the release candidate on each supported platform. See the 'Supported Platforms' table below.
2. On each supported platform, perform an installation into a local, empty directory. Name the directory after the platform, e.g. ~svn/osx/osx_install_dir.
3. On each supported platform, compress the local install directory to a name that matches its root directory (e.g. gpstk.mac.osx.tar.gz for the Mac release) with a command like tar -cvzf ~/svn/osx/osx_install_dir gpstk-1.7.mac.osx.tar.gz. For the windows release we use a program called "Advanced Installer" to create an "MSI" to install with. Instructions for using Advanced Installer.
4. On each supported platform, generate and record an md5sum and sha1sum keys for the compressed file, using commands like md5sum gpstk-1.7.mac.osx.tar.gz > osx_check.md5 and sha1sum gpstk-1.7.mac.osx.tar.gz > osx_check.sha1.
5. Upload the source tarball, source zip, and precompiled applications to SourceForge and post the md5sum and sha1sum authentication keys.
6. Send an announcement of the release to the gpstk-announce list.
7. Update the site news on SourceForge.
8. Update the freshmeat project description.
9. Update the ReleaseSchedule to note the date of the release. Move the entry from the proposed to historical portion of the page.

1.5 Reintegrating Changes Made in the Branch into the Trunk

1. Check out a copy of the dev tree in the trunk.
2. Determine the changes made to the branch and the trunk from time of branching (r####) to now by looking at the log i.e. svn log -vr r####:HEAD.
3. Merge the branch changes back into the trunk with svn merge. From the dev/ directory, a sample command would be svn merge -r r####:HEAD https://gpstk.svn.sourceforge.net/svnroot/RC1.7.
4. Resolve any conflicts caused by the merge and commit (svn commit).
5. Delete the release candidate branch using svn delete.

2 Supported Platforms and their Naming Conventions

3 Numbering Conventions

The numbering convention for stable releases of the GPSTk is X.Y.Z. For example, 1.0.2 was a release of the GPSTk. X is the major release number, Y is the minor release number, Z is the revision number.

- X is incremented when large scale features have been altered. Several class hierarchies have been replaced. Backwards compatibility is not guaranteed. - Y is incremented when existing interfaces have been changed. A few class hierarchies may have been replaced. - Z is incremented when a bug has been fixed, and no interfaces have changed.

4 Quick Reference Guide

Overview

4.1 Preparation for a New Release Candidate

4.2 Creating a Release Candidate

4.3 Testing and Verification of the Release Candidate

5 Releasing the Release Candidate as a New Version

-- BenHarris - 23 Oct 2006

• gpstk.perforce.chno.11627.tar.gz: Very last version of GPSTk dev tree in perforce repository. Change number 11627