Releasing

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 to be published on the Snowpack repository.

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

Preparing the assets

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

Internal releasesOfficial releases

although this is not mandatory, it makes sense to address all warnings on all platforms you need to support
Please check that the whole compilation process (including detection of auxiliary components such as MeteoIO) works properly on all platforms you need to support
Commit any changes you've made

Of course, the warnings should be addressed (they should never have showed up in the git master) 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 such as MeteoIO) 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

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 described in Getting-started.

Internal releasesOfficial releases

Either do a fresh checkout of all components to a new location (like for official releases) or you can get away with making a make distclean and removing all files in lib/ (make sure you also have a clean doc directory). But a clean checkout is still recommended...

For MeteoIO:
- do a default ccmake ., enabling "install doc" and "bundle all" (see below)
- in cmake, choose:
  - BUILD_SHARED_LIBS OFF (at least on Windows)
  - 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_GIT ON if your sources come from a git clone (using the git 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
- 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:
- do a default ccmake ., enabling "install doc" and "bundle all" (see below)
- in cmake, choose:
  - BUILD_SHARED_LIBS OFF (at least on Windows)
  - 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_GIT ON if your sources come from a git clone (using the git 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)
- compile with make
- prepare the documentation with make doc (you need doxygen and it is recommended to have graphviz for generating dependency graphs)

There is no need to prepare Linux binaries as they will be automatically done by Gitlab pipelines. The same applies to source code and documentation-only packages. The generation of the release by Gitlab will be triggered by creating a new tag, see below.

Do a fresh checkout of all components to a new location (so you don't have non-committed files left over from your own work)
For MeteoIO:
- do a default ccmake ., enabling "install doc" and "bundle all" (see below)
- in cmake, choose:
  - BUILD_SHARED_LIBS OFF (at least on Windows)
  - INSTALL_DOC ON
  - CMAKE_BUILD_TYPE release
  - DEST "safe" so it works on all computers
  - VERSION_FROM_GIT OFF in order to get the official release number
  - CPACK_BUNDLE_ALL ON in order to generate one installer containing everything that is needed
- 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:
- do a default ccmake ., enabling "install doc" and "bundle all" (see below)
- in cmake, choose:
  - BUILD_SHARED_LIBS OFF (at least on Windows)
  - INSTALL_DOC ON
  - CMAKE_BUILD_TYPE release
  - DEST "safe" so it works on all computers
  - VERSION_FROM_GIT OFF in order to get the official release number
  - CPACK_BUNDLE_ALL ON in order to generate one installer containing everything that is needed (including meteoio)
- compile with make
- prepare the documentation with make doc (you need doxygen and it is recommended to have graphviz for generating dependency graphs)

Preparing the changelogs

Internal releasesOfficial releases

This is not needed for internal releases.

Get all the logs since the last release: get the matching git version number from the tags tree, then do a git log --name-only XXX..master > Changelog_full.txt where XXX is the starting git 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, copy/paste your changelog into it. Check with a preview before committing! (for example, running mkdocs serve on the snowpack-web repository)
Link to your new changelog in the Changelogs page

Packaging & distribution

Packaging

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

Redo ccmake . so that it finds the newly compiled libraries
Do cpack on Linux and Windows, cpack PackageMaker on MacOS
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 MacOS: 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 .git directories from it: find snowpack-X.X.X-doc -type d -name ".git" | xargs -i rm -Rf {}
- pack the documentation: tar -czvf snowpack-X.X.X-doc.tgz snowpack-X.X.X-doc/
Create the source code package if necessary (on Gitlab, this is done automatically):
- Generate the source package by doing make package_source (it is usually easier to do it on Linux)

In the end, you should have the following packages:

Internal releasesOfficial releases

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

no need to have Linux binaries, source packages or documentation-only package as they will be handled by Gitlab pipelines (see below)
for MacOS, a dmg
for Windows, an exe installer

Distribution

Internal releasesOfficial releases

Provide all packages on a shared drive or a web server (such as Nextcloud).

The Linux binaries, the source code packages and the documentation-only packages are automatically generated by Gitlab pipelines. These pipelines are triggered when a new tag is pushed to master. Windows and MacOS releases still need to be prepared on the side, uploaded as packages and manually added to releases.

Creating a new tag

Git tags capture a point in history of the repository. There are both lightweight tags and annotated tags, only the later is of interest here. Annotated tags are created with some kind of name and a commit message: for example git tag -a 2.23.0 -m "Creating tag 2.23.0" to create tag "2.23.0". Such a tag needs to be pushed to master : git push origin 2.23.0.

Existing tags can be listed: git tag

In case of errors, it is possible to delete a tag (keeping in mind that you might need to also cancel any pipeline that is running based on this tag and that releases and other artifacts based on this tag might or might not be automatically deleted too): git push --delete origin 2.23.0 (to delete the remote tag) as well as git tag -d 2.23.0 to delete the local tag.

Uploading a Generic Package

GitLab offers a Package Registry to publish and share packages. Files can be uploaded as Generic Packages via the GitLab Packages API (please check for the package version from the pipeline if you want to add assets to a release):

curl --header "PRIVATE-TOKEN: <YOUR_ACCESS_TOKEN>" \
     --upload-file <PATH_TO_FILE> \
     "https://code.wsl.ch/api/v4/projects/<PROJECT_ID>/packages/generic/<PACKAGE_NAME>/<PACKAGE_VERSION>/<FILE_NAME>"

The PROJECT_ID can be taken from the following table:

Project	PROJECT_ID
MeteoIO	30
Snowpack	32
Inishell	36
Alpine3D	11

So, for example to publish a new Snowpack package with the glpat-a2Uz_lepHuiP0L1QC_7x access token, use something like:

curl --header "PRIVATE-TOKEN: glpat-a2Uz_lepHuiP0L1QC_7x" \
     --upload-file ./Snowpack-3.0.6-x86_64.tar.gz \
     "https://code.wsl.ch/api/v4/projects/32/packages/generic/snowpack/3.0.6/Snowpack-3.0.6-x86_64.tar.gz"

Read more about Generic Packages in the documentation: Generic Packages

Creating or editing a GitLab Release

Next, we can create a Release on GitLab Releases. We press the button "New Release" and select the Tag name that represents our release. After adding a title and some optional release notes, we can link to our packages we created before.

If a release already exists, we can edit it and add our additional links to it.

Note If you use Gitlab CI variables, the default behaviour is protected, which means those variables are not accessible on not protected branches (which are so created by default). So either protect the branch or make the variable public. Releasing with a tag runs on a detached pipeline, i.e. protected variables are not accessible. (This is important for the SSH-related variables)

Releasing

Preparing the assets

Preparing the documentation

Preparing the source code

Compiling the various components

Preparing the changelogs

Packaging & distribution

Packaging

Distribution

Creating a new tag

Uploading a Generic Package

Creating or editing a GitLab Release

Further reading