Goby Release Procedure
This page describes the process for making a formal software release of the Goby project.
An ant script exists to aid in the process of bundling a new release for public distribution. This exists in the root directory of the Goby source tree. The release script will tag the Goby project in the subversion repository so that the contents of the release can be tracked back to the source. The script only bundles what is in the main trunk of the subversion repository and NOT what exists on the local disk. This is intentional since it is essential that we know exactly what is in the distribution.
The user creating the release must have write access to Goby in subversion. Once the development team is confident that the source code is stable, the source tree and associated data and configuration files must be tagged, bundled and uploaded to the http://goby.campagnelab.org/ web site for distribution.
$ svn co https://pbtech-vc.med.cornell.edu/public/svn/icb/trunk/goby $ cd goby
Edit * python/setup.py * cpp/configure.ac to set the new version number.
$ svn commit -m 'updated version numbers for python and c++ APIs' $ ant -f release.xml Enter a revision for the build: Reply "stable" Enter a tag for the build [goby_yyyyMMddHHmmss]
At this point you must decide on a tag for the build. This is what will be used to identify the version of the source that was used to create the software bundle. A suggested default using the current data and time however formal releases may have more traditional version numbers (i.e., 2.4.1). To accept the default tag simply press enter or type a new tag and press enter. Please note that the tag should not include any spaces or other characters that are not valid in a filename. After the tag has been entered entered, the script will tag the code in subversion as https://pbtech-vc.med.cornell.edu/public/svn/icb/tags/goby_yyyyMMddHHmmss (or the tag that was provided to the script). The code will be retrieved using the new tag, compiled, jarred, and zipped for distribution. The files intended for distribution will be placed into a directory called release-goby_yyyyMMddHHmmss. An example of a release structure using the tag goby_1.9.6 is as follows:
$ ls -l release-goby_1.9.6/ CHANGES.txt VERSION.txt goby-api.jar goby-apidoc.zip -> goby_1.9.6-apidoc.zip goby-cpp.zip -> goby_1.9.6-cpp.zip goby-data.zip -> goby_1.9.6-data.zip goby-deps.zip -> goby_1.9.6-deps.zip goby-src.zip -> goby_1.9.6-src.zip goby.jar goby.zip -> goby_1.9.6-goby.zip goby_1.9.6-apidoc.zip goby_1.9.6-cpp.zip goby_1.9.6-data.zip goby_1.9.6-deps.zip goby_1.9.6-goby.zip goby_1.9.6-src.zip
The src, cpp, data, and deps files contain source code and other files used to create Goby. Note the presence of softlinks that use a generic name to the specific version file. These are set up so that the download site does need to change every time a new release is made. For convenience the release procedure also creates a compressed tar file of all the release files.
Before sending the release out, some testing should be performed. Open and execute each of the jar files and run a few examples. At this point, the release files need to be placed on the web server. This requires access to the account "www". The entire Goby release directory should be copied to /var/www/dirs/chagall/goby/releases/ on okeeffe. For example:
$ scp release-goby_1.9.6.tgz www@okeeffe:/var/www/dirs/chagall/goby/releases/
Uncompress the release file on okeeffe:
$ ssh www@okeeffe $ cd /var/www/dirs/chagall/goby/releases/ $ tar zxvf release-goby_1.9.6.tgz
Check the permissions on the files and make sure they all readable by everyone since the web server process needs to be able to access them.
At this point there are a few links that need to be updated on the Goby download page. We keep explicit links to the "latest" release and all major previous releases. Assuming the previous release was goby_1.9.6 and the new release is goby_1.9.6, update the link for the latest-release to point to the new version:
[www@okeeffe releases]$ ls -ld latest-release lrwxrwxrwx 1 www www 16 Jul 8 13:22 latest-release -> release-goby_1.9.6 [www@okeeffe releases]$ rm -i latest-release rm: remove symbolic link `latest-release'? y [www@okeeffe releases]$ ln -s release-goby_1.9.6 latest-release
And add the previous version to the list of archive releases:
[www@okeeffe archive]$ cd archive [www@okeeffe archive]$ ln -s ../release-goby_1.9.6 .
Once the release has been made, the release tag should be entered into the GitHub issue tracker. Any issues fixed in this release should be closed and refer to the new tag.
Naturally, it is extremely important to make sure all the links are valid and the distribution has not been corrupted during the copy/edit process. Also note that the download page is set up to automatically read the "VERSION.txt" file from the release so make sure to check that this shows up properly on the web site.
Push the new tag to GitHub:
git remote set-url origin email@example.com:CampagneLaboratory/goby.git git push --tags origin
Update the ChangeLog page at http://campagnelab.org/software/goby/change-log/
Post an announcement to the Goby user forum https://groups.google.com/forum/?fromgroups#!forum/goby-framework.
The latest Python API needs to be pushed to PyPI. These steps assume you are using an account on one of the Linux systems.
Make sure you are using an appropriate version of Python and have PYTHONPATH set (you might want to add these to the .bash_profile file for your account).
$ slchoose python 2.5 gcc_64 $ export PYTHONPATH=/home/YOUR_USERNAME/python/lib/python/
Protobuf (2.3.0) for Python needs to be installed just once for your account. We'll assume you ALREADY have the Protobuf library installed (see the README.txt for Goby C/C++ API if you don't). Specifically for Python:
$ cd protobuf-2.3.0/python/ $ mkdir -p /home/YOUR_USERNAME/python/lib/python/ $ python setup.py install --home /home/YOUR_USERNAME/python/
PyJavaProperties is also needed for the Goby Python API. If you don't have it installed, download it from http://pypi.python.org/pypi/pyjavaproperties/ then untar it and to install it
$ tar zxvf pyjavaproperties-VERSION.tar.gz $ cd pyjavaproperties-VERSION $ python setup.py install --home /home/YOUR_USERNAME/python/
To push the latest version of the Goby Python API to PyPI
$ cd YOUR_GOBY_DIR/python/ $ python setup.py register sdist upload
If you haven't previously logged into PyPI you will need to provide an appropriate username and password for the Goby project on PyPI. If you forgot to edit the setup.py to change the version number (as mentioned at the very top of this document), you'll get an error here. The rest of the process is automatic. You can visit http://pypi.python.org/pypi/goby/ to verify the new upload.
Update, as necessary:
Gobyweb Plugins Gobyweb-dev Plugins gobyweb@spanky:~/goby-dev/goby.jar gobyweb@spanky:~/goby/goby.jar
Finally, an announcement message should be set to the Goby mailing list at firstname.lastname@example.org