GPS Toolkit Release Process

Check out the ReleaseSchedule for the proposed upcoming releases.

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 Git 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 Git iteration (currently only hosted internally at ARL).
  • 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:

ProcessDiagram.png

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 Git 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 gpstk-devel 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. Update gpstk/dev/JamRules and gpstk/dev/configure.ac 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 Git repository and take note of the revision hash number (#######).
  10. Create a branch of the dev tree with git branch RCXX. Call it by the Release Candidate number chosen e.g. RC1.7.
  11. For each supported platform, prepare a directory for platform-specific testing of the release candidate, i.e. ~/git/osx, ~/git/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 cmake, make, and make 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 Git 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 Git 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 Git 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 Git 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. ~git/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 gpstk-1.7.mac.osx.tar.gz ~/git/osx/osx_install_dir. 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 (#######) to now by looking at the log i.e. git log --pretty=oneline --abbrev-commit #######..HEAD.
  3. Merge the branch changes back into the trunk with git checkout master and git merge vXX.
  4. Resolve any conflicts caused by the merge.
  5. Delete the release candidate branch using git branch -D vXX.

2 Supported Platforms and their Naming Conventions

System(s) Architecture Compiler Name
Windows 2000, XP, 7 x86 MS Visual Studio 2012 gpstk.win32
Windows 2000, XP, 7 x64 MS Visual Studio 2012 gpstk.win64
Linux 64bit Intel, AMD gcc 4.x gpstk.linux.x86_64
Mac OSX 64bit Intel clang 425.x.x gpstk.mac.osx
Solaris 10 Sparc Sun Studio 12.x C++ gpstk.solaris.sparc

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

%IMGLNK{"ReleaseCandidateOverview.png"}%

4.1 Preparation for a New Release Candidate

%IMGLNK{"PrepforNewRC.png"}%

4.2 Creating a Release Candidate

%IMGLNK{"CreatinganRC.png"}%

4.3 Testing and Verification of the Release Candidate

%IMGLNK{"TestingandVerificationofRC.png"}%

5 Releasing the Release Candidate as a New Version

%IMGLNK{"ReleasingRC.png"}%

-- BryanParsons - 05 Sep 2013

Topic attachments
I Attachment Action Size Date Who Comment
ProcessDiagram.pngpng ProcessDiagram.png manage 11.6 K 10 Jan 2007 - 20:54 AdminRickMach  
SolarisList.txttxt SolarisList.txt manage 18.8 K 27 Nov 2006 - 20:32 EricHagen List of Problems with Solaris Jam
gpstk.linux.x386TEST.tar.gzgz gpstk.linux.x386TEST.tar.gz manage 18787.2 K 10 Nov 2006 - 19:26 EricHagen  
gpstk.perforce.chno.11627.tar.gzgz gpstk.perforce.chno.11627.tar.gz manage 5583.7 K 08 Nov 2006 - 22:41 BenHarris Very last version of GPSTk dev tree in perforce repository. Change number 11627
gpstkRC1_2_348.tar.gzgz gpstkRC1_2_348.tar.gz manage 6425.3 K 15 Dec 2006 - 17:04 EricHagen Release Candidate for GPSTK - version 348
Topic revision: r36 - 05 Dec 2013, AdminBryanParsons
 

This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback