icinga2/RELEASE.md

Release Workflow

Table of Content

• 1. Preparations
  • 1.1. Issues
  • 1.2. Backport Commits
  • 1.3. Windows Dependencies
• 2. Version
• 3. Changelog
• 4. Git Tag
• 5. Package Builds
  • 5.1. RPM Packages
  • 5.2. DEB Packages
• 6. Build Server
• 7. Release Tests
• 8. GitHub Release
• 9. Docker
• 10. Post Release
  • 10.1. Online Documentation
  • 10.2. Announcement
  • 10.3. Project Management

Preparations

Specify the release version.

VERSION=2.11.0

Add your signing key to your Git configuration file, if not already there.

vim $HOME/.gitconfig

[user]
        email = michael.friedrich@icinga.com
        name = Michael Friedrich
        signingkey = D14A1F16

Issues

Check issues at https://github.com/Icinga/icinga2

Backport Commits

For minor versions you need to manually backports any and all commits from the master branch which should be part of this release.

Windows Dependencies

In contrast to Linux, the bundled Windows dependencies (at least Boost and OpenSSL) aren't updated automatically. (Neither by Icinga administrators, nor at package build time.)

To ensure the upcoming Icinga release ships the latest (i.e. most secure) dependencies on Windows:

Update packages.icinga.com

Add the latest Boost and OpenSSL versions to https://packages.icinga.com/windows/dependencies/ like this:

localhost:~$ ssh aptly.vm.icinga.com
aptly:~$ sudo -i
aptly:~# cd /var/www/html/aptly/public/windows/dependencies
aptly:dependencies# wget https://master.dl.sourceforge.net/project/boost/boost-binaries/1.76.0/boost_1_76_0-msvc-14.2-64.exe
aptly:dependencies# wget https://master.dl.sourceforge.net/project/boost/boost-binaries/1.76.0/boost_1_76_0-msvc-14.2-32.exe
aptly:dependencies# wget https://slproweb.com/download/Win64OpenSSL-1_1_1k.exe
aptly:dependencies# wget https://slproweb.com/download/Win32OpenSSL-1_1_1k.exe

Ensure Compatibility

Preferably on a fresh Windows VM (not to accidentally build Icinga with old dependency versions) setup a dev environment using the new dependency versions:

1. Download doc/win-dev.ps1
2. Edit your local copy, adjust the dependency versions
3. Ensure there are 35 GB free space on C:
4. Run the following in an administrative Powershell:
   1. Enable-WindowsOptionalFeature -FeatureName "NetFx3" -Online (reboot when asked!)
   2. powershell -NoProfile -ExecutionPolicy Bypass -File "${Env:USERPROFILE}\Downloads\win-dev.ps1" (will take some time)

Actually clone and build Icinga using the new dependency versions as described here. Fix incompatibilities if any.

Update Build Server, CI/CD and Documentation

• https://git.icinga.com/infra/ansible-windows-build (don't forget to provision!)
• doc/21-development.md
• doc/win-dev.ps1 (also affects CI/CD)
• tools/win32/configure.ps1
• tools/win32/configure-dev.ps1

Re-provision Build Server

Even if there aren't any new releases of dependencies with versions hardcoded in the repos and files listed above (Boost, OpenSSL). There may be new build versions of other dependencies (VS, MSVC). Our GitHub actions (tests) use the latest ones automatically, but the GitLab runner (release packages) doesn't.

Version

Update the version:

perl -pi -e "s/Version: .*/Version: $VERSION/g" ICINGA2_VERSION

Changelog

Choose the most important issues and summarize them in multiple groups/paragraphs. Provide links to the mentioned issues/PRs. At the start include a link to the milestone's closed issues.

Git Tag

git commit -v -a -m "Release version $VERSION"

Create a signed tag (tags/v) on the master branch (for major releases) or the support branch (for minor releases).

git tag -s -m "Version $VERSION" v$VERSION

Push the tag:

git push origin v$VERSION

For major releases: Create a new support branch:

git checkout master
git push

git checkout -b support/2.12
git push -u origin support/2.12

Package Builds

mkdir $HOME/dev/icinga/packaging
cd $HOME/dev/icinga/packaging

RPM Packages

git clone git@git.icinga.com:packaging/rpm-icinga2.git && cd rpm-icinga2

DEB Packages

git clone git@git.icinga.com:packaging/deb-icinga2.git && cd deb-icinga2

Raspbian Packages

git clone git@git.icinga.com:packaging/raspbian-icinga2.git && cd raspbian-icinga2

Windows Packages

git clone git@git.icinga.com:packaging/windows-icinga2.git && cd windows-icinga2

Branch Workflow

For each support branch in this repo (e.g. support/2.12), there exists a corresponding branch in the packaging repos (e.g. 2.12). Each package revision is a tagged commit on these branches. When doing a major release, create the new branch, otherweise switch to the existing one.

Switch Build Type

Ensure that ICINGA_BUILD_TYPE is set to release in .gitlab-ci.yml. This should only be necessary after creating a new branch.

variables:
  ...
  ICINGA_BUILD_TYPE: release
  ...

Commit the change.

git commit -av -m "Switch build type for 2.13"

RPM Release Preparations

Set the Version, revision and %changelog inside the spec file:

perl -pi -e "s/Version:.*/Version:        $VERSION/g" icinga2.spec

vim icinga2.spec

%changelog
* Thu Sep 19 2019 Michael Friedrich <michael.friedrich@icinga.com> 2.11.0-1
- Update to 2.11.0

DEB and Raspbian Release Preparations

Update file debian/changelog and add at the beginning:

icinga2 (2.11.0-1) icinga; urgency=medium

  * Release 2.11.0

 -- Michael Friedrich <michael.friedrich@icinga.com>  Thu, 19 Sep 2019 10:50:31 +0200

Windows Release Preparations

Update the file .gitlab-ci.yml:

perl -pi -e "s/^  UPSTREAM_GIT_BRANCH: .*/  UPSTREAM_GIT_BRANCH: v$VERSION/g" .gitlab-ci.yml
perl -pi -e "s/^  ICINGA_FORCE_VERSION: .*/  ICINGA_FORCE_VERSION: v$VERSION/g" .gitlab-ci.yml

Release Commit

Commit the changes and push the branch.

git commit -av -m "Release $VERSION-1"
git push origin 2.11

GitLab will now build snapshot packages based on the tag v2.11.0 of Icinga 2.

Package Tests

In order to test the created packages you can download a job's artifacts:

Visit git.icinga.com and navigate to the respective pipeline under CI / CD -> Pipelines.

There click on the job you want to download packages from.

The job's output appears. On the right-hand sidebar you can browse its artifacts.

Once there, navigate to build/RPMS/noarch where you'll find the packages.

Release Packages

To build release packages and upload them to packages.icinga.com tag the release commit and push it.

RPM/DEB/Raspbian:

git tag -s $VERSION-1 -m "Release v$VERSION-1"
git push origin $VERSION-1

Windows:

git tag -s $VERSION -m "Release v$VERSION"
git push origin $VERSION

Now cherry pick the release commit to master so that the changes are transferred back to it.

Attention: Only the release commit. NOT the one switching the build type!

Build Infrastructure

https://git.icinga.com/packaging/rpm-icinga2/pipelines https://git.icinga.com/packaging/deb-icinga2/pipelines https://git.icinga.com/packaging/windows-icinga2/pipelines https://git.icinga.com/packaging/raspbian-icinga2/pipelines

• Verify package build changes for this version.
• Test the snapshot packages for all distributions beforehand.

Once the release repository tags are pushed, release builds are triggered and automatically published to packages.icinga.com

Release Tests

• Test DB IDO with MySQL and PostgreSQL.
• Provision the vagrant boxes and test the release packages.
• Test the setup wizard inside a Windows VM.
• Start a new docker container and install/run icinga2.

CentOS

docker run -ti centos:7 bash

yum -y install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
yum -y install epel-release
yum -y install icinga2
icinga2 daemon -C

Ubuntu

docker run -ti ubuntu:bionic bash

apt-get update
apt-get -y install apt-transport-https wget gnupg

wget -O - https://packages.icinga.com/icinga.key | apt-key add -

. /etc/os-release; if [ ! -z ${UBUNTU_CODENAME+x} ]; then DIST="${UBUNTU_CODENAME}"; else DIST="$(lsb_release -c| awk '{print $2}')"; fi; \
 echo "deb https://packages.icinga.com/ubuntu icinga-${DIST} main" > \
 /etc/apt/sources.list.d/${DIST}-icinga.list
 echo "deb-src https://packages.icinga.com/ubuntu icinga-${DIST} main" >> \
 /etc/apt/sources.list.d/${DIST}-icinga.list

apt-get update

apt-get -y install icinga2
icinga2 daemon -C

GitHub Release

Create a new release for the newly created Git tag: https://github.com/Icinga/icinga2/releases

Hint: Choose tags, pick one to edit and make this a release. You can also create a draft release.

The release body should contain a short changelog, with links into the roadmap, changelog and blogpost.

Post Release

Online Documentation

Only required for major releases.

Navigate to puppet-customer/icinga.git and do the following steps:

Testing

git checkout testing && git pull
vim files/var/www/docs/config/icinga2-latest.yml

git commit -av -m "icinga-web: Update docs for Icinga 2"

git push

SSH into the webserver and do a manual Puppet dry run with the testing environment.

puppet agent -t --environment testing --noop

Once succeeded, continue with production deployment.

Production

git checkout master && git pull
git merge testing
git push

SSH into the webserver and do a manual Puppet run from the production environment (default).

puppet agent -t

Manual Generation

SSH into the webserver or ask @bobapple.

cd /usr/local/icinga-docs-tools && ./build-docs.rb -c /var/www/docs/config/icinga2-latest.yml

Announcement

• Create a new blog post on icinga.com/blog including a featured image
• Create a release topic on community.icinga.com
• Release email to net-tech & team

Project Management

• Add new minor version on GitHub.