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 GPSTkCodingStnadards^?, 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 and vice versa. A Perl script has been written for this task JamfileTest.pl .
4. Review and update gpstk/dev/AUTHORS to include recent contributors.
5. 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.2.
2. Update gpstk/dev/NEWS with the date and version number.
3. Update gpstk/dev/Changelog with the activities of the last week.
4. Generate/Update a README describing the GPSTk, referencing the GPSTk website/TWiki, and a description of the files contained at a high level.
5. Generate/Update an INSTALL text file describing how to install the binaries.
6. Update the repository with the above changes.
7. Check out a fresh copy of the dev tree from the Subversion repository and take note of the revision number.
8. Create a branch of the dev tree with svn copy. Call it by the Release Candidate number chosen e.g. RC1.2. 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.2/ -m "Branching for RC1.2 from revison number r###"

• It is importatnt 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.

1. Check out a fresh copy of the branch tree (eg RC1.2) from the Subversion repository with svn update.
2. Copy the branch directory and rename it "gpstk". Note: This is only on the local machine not a change in the repository. Example: cp -r RC1.2/  gpstk/
3. Tar and zip that directory "gpstk" and exclude Subversion specific files using a command like tar -cvfz gpstkRC.tar.gz gpstk --exclude ".svn". This is the GPSTk release candidate.
4. It is recommended that the directory "gpstk" now be deleted to remain consistent with the repository. Again this is a change that has only taken place on the local machine.
5. Create an md5sum and sha1sum for the release candidate.
6. For each supported platform in this release (See Supported Platforms below), transfer a copy of the release candidate to a system which uses that platform.
7. For each supported platform, verify that the release candidate has not been altered or tampered with by verifying the md5sum and sha1sum.

1.3 Testing and Verification of the Release Candidate

1. First verify that the release candidate compiles and builds for each supported platform by detaring and unzipping the release candidate and building the GPSTk using jam and then jam install. 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 9 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. For revision 1.2 specifically, use the last perforce revision of the GPSTk within ARL:UT. 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. 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 source tarball for each supported platform. See the 'Supported Platforms' table below.
2. On each supported platform preform an installation into a local, empty directory. Name the directory after the platform.
3. On each supported platform, compress the local install directory to a name that matches its root directory e.g. gpstk.win32.zip for the Windows release.
4. On each supported platform, generate and record an md5sum and sha1sum keys for the compressed file.
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.

1.5 Reintegrating Changes Made in the Branch into the Trunk

1. Rename the branch directory from release candidate to version number e.g. RC1.2 --> v1.2 .
2. Determine the changes made to the branch and the trunk from time of branching (r###) to now by looking at the log ie svn log -vr r###:HEAD.
3. Merge changes back into the trunk with svn merge and svn commit.
4. Resolve any conflicts caused by the merge and commit.

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 Refrence Guide

Overview

4.1 Preperation 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