snowpack

HowToRelease

You are looking at an old revision of the page HowToRelease. This revision was created by cesar vera.

Table of Content

How to prepare a public release

Introduction

Packaging Snowpack could be done for several reasons, the main being:

  • for creating an internal release that an IT department can make available
  • for creating an official release

Both cases are covered by this documentation, the first one being the simplest one (no need to perform in depth checks of the release).

Backports to trunk

Since 03/2014, all development is performed on branches/dev and trunk only receives bug fixes to the last stable release. It is therefore necessary to consider what should be brought from dev into trunk before preparing a release: either everything (when preparing a major release) or cherry picking some bug fixes (during the lifetime of the current stable release).

Synchronizing from trunk

Simply run "svn merge https://models.slf.ch/svn/snowpack/branches/dev" in order to synchronize the trunk with the latest revision of dev.

Cherry picking

First open the logs of dev and write down all the revisions that should be merged into the trunk. Then, go to a clean trunk checkout and do, for each revision and in increasing order: "svn merge -c {revision_number} https://models.slf.ch/svn/snowpack/branches/dev"

Make sure to resolve all potential conflicts before picking the next commit. Once this has been done, commit these changes to trunk.

Internal release

The goal is to prepare a specific version of Snowpack for internal redistribution. This is usually performed by the local IT and made available in binary form (read: installer) for all users. The requirements regarding code polishing, making sure that the milestones have been reached, promoting the release are all removed, making the whole process simpler.

Compiling the various components

The goal is to compile the source code of meteoio and snowpack as well as prepare the documentation. It is highly recommended to follow the source setup discribed in Getting-started.

  • For MeteoIO
    • remove all previous objects, libraries, etc by making a "make distclean" and removing all files in lib/
    • in cmake, choose: - INSTALL_DOC ON - CMAKE_BUILD_TYPE release - DEST optimized only if your binary would be distributed on computers with the same instructions set as the computer doing the compilation, otherwise choose "safe" - VERSION_FROM_SVN ON if your sources come from an svn checkout (using the svn version as release number gives much better information when reporting issues)
    • compile with "make"
    • prepare the documentation with "make doc" (you need doxygen and it is recommended to have graphviz for generating dependency graphs)
  • For Snowpack
    • remove all previous objects, libraries, etc by making a "make distclean" and removing all files in lib/
    • in cmake, choose: - INSTALL_DOC ON - CMAKE_BUILD_TYPE release - DEST optimized only if your binary would be distributed on computers with the same instructions set as the computer doing the compilation, otherwise choose "safe" - VERSION_FROM_SVN ON if your sources come from an svn checkout (using the svn version as release number gives much better information when reporting issues) - CPACK_BUNDLE_ALL ON in order to generate one installer containing everything that is needed (including meteoio and inishell)
    • compile with "make"
    • prepare the documentation with "make doc" (you need doxygen and it is recommended to have graphviz for generating dependency graphs)
  • Auxiliary components
    • compile inishell with "ant snowpack". This bundles the snowpack.xml file in the jar

Packaging

See packaging instructions

Official release

When creating an official release for Snowpack, several things must be done, both in term of source code management, documentation and packaging. This Howto should provide a step by step description of what has to be done.

Preparing auxiliary components

Snowpack now depends on several other components that must be available as stable releases (either released at the same time as Snowpack or on a separate schedule). These are MeteoIO and inishell.

  • Remove all previous installed version of the auxiliary components
  • Install all auxiliary components in their last stable release
  • On Windows, there is currently a bug in cmake preventing it from handling properly paths with spaces. So meteoio must be installed to a path that does not contain any spaces in order to be properly detected

Preparing the changelog

  • Get all the logs since the last release: get the matching svn number from the tags tree, then do a svn log -rXXX:HEAD > Changelog_full.txt where XXX is the starting svn version
  • Open the full changelog as well as an empty file side by side.
  • Start the new file with something like "This is the changelog for Snowpack release 3.1.0"
  • As you go through the full changelog, add items to the new file
  • Once you've reached the end of the full changelog, close it and focus on the new changelog
  • Try grouping the items you wrote by categories, rephrasing them if necessary. Follow the markdown syntax. You can also edit a previous changelog to copy the style.
  • Once this is done, create a new page in the documentation tab of the Snowpack forge. Name it as ChangelogX-X-X with X-X-X being the release number. Use "Brief changelog of Snowpack-X.X.X" as page description. Copy/paste your changelog in the content section, add label "Phase:QA". Check with a preview before committing!
  • Link your new changelog in the Changelogs page
  • Add label "Deprecated" to the previous changelog

Preparing the documentation

  • Obviously, the doxygen documentation must be up to date with the current status of the code. Please also fix all doxygen warnings
  • Edit the file config.dox in the source code directory and update the documentation version number (key PROJECT_NUMBER) to the release number
  • If new graphic files have been prepared, please make sure they show at the proper size in the html and pdf versions
  • Commit any changes you've made

Preparing the source code

  • Of course, the warnings should be suppressed (they should never have showed up in the svn trunk) or silenced (for the warnings that have a good reason to stay) on all supported platforms
  • Please check that the whole compilation process (including detection of auxiliary components) works properly on all platforms
  • Update the release number in CMakeLists.txt as well as in snowpack.lsm. The later should also contain the release date.
  • Commit any changes you've made
  • Check out Snowpack to a fresh location
  • Do a default "ccmake .", enabling "install doc" and "bundle all"
  • Generate the source package by doing "make package_source" (it is usually easier to do it on Linux)
  • Compile (make) and generate the documentation (make doc)

Packaging

On Windows, you have to install the Nullsoft Scriptable Install System (NSIS) in order to prepare the packages.

  • Copy the inishell.jar file in tools/
  • Redo "ccmake ." so that it finds the newly compiled libraries
  • Do "cpack" on Linux and Windows, "cpack PackageMaker" on osX
  • Check that the packages work properly:
    • on Linux: it should have created a tarball, a deb and an rpm. Open then with gdebi and browse what they contain if you don't want to have to install them
    • on osX: install the dmg and explore the newly installed application
    • on Windows: run the installer and explore the newly installed application, also checking the start menu shortcuts (you can also explore cpack's temporary directory to check if all files have been gathered).
    • The packages should contain:
      • the libraries (as .dll or .dylib or .so as well as .a) for snowpack and meteoio
      • the includes for snowpack and meteoio
      • the html documentation for snowpack and meteoio
      • the examples for snowpack and meteoio
  • Create the documentation only package from the documentation:
    • copy or move the doc/ directory as snowpack-X.X.X-doc (X.X.X being the release number)
    • remove the .svn directories from it: find snowpack-X.X.X-doc -type d -name ".svn" | xargs -i rm -Rf {}
    • pack the documentation: tar -czvf snowpack-X.X.X-doc.tgz snowpack-X.X.X-doc/

In the end, you should have the following packages:

  • for Linux, a binary tarball as well as a deb and an rpm
  • for osX, a dmg
  • for Windows, an exe installer
  • a documentation only package
  • a source package

Distribution

  • Go to the Snowpack forge Download page, open it in two browser's tabs
  • Open the last download of the previous release in one tab
  • Click on "New download" in the second tab
  • Copy/paste and modify the previous description to the new download, including file names and tags
  • Point the new download to the matching archive on your disk and create the download
  • Add "Deprecated" as the last tag of the matching download of the previous release (in the first tab)
  • Proceed along these lines for all downloads