icinga2/RELEASE.md

422 lines
11 KiB
Markdown
Raw Normal View History

2018-04-24 14:51:26 +02:00
# Release Workflow <a id="release-workflow"></a>
#### Table of Content
- [1. Preparations](#preparations)
- [1.1. Issues](#issues)
- [1.2. Backport Commits](#backport-commits)
2021-06-24 19:22:56 +02:00
- [1.3. Windows Dependencies](#windows-dependencies)
2018-04-24 14:51:26 +02:00
- [2. Version](#version)
- [3. Changelog](#changelog)
- [4. Git Tag](#git-tag)
- [5. Package Builds](#package-builds)
- [5.1. RPM Packages](#rpm-packages)
- [5.2. DEB Packages](#deb-packages)
2019-09-19 13:49:31 +02:00
- [6. Build Server](#build-infrastructure)
2018-04-24 14:51:26 +02:00
- [7. Release Tests](#release-tests)
- [8. GitHub Release](#github-release)
2020-10-14 09:27:29 +02:00
- [9. Docker](#docker)
- [10. Post Release](#post-release)
- [10.1. Online Documentation](#online-documentation)
- [10.2. Announcement](#announcement)
- [10.3. Project Management](#project-management)
2018-04-24 14:51:26 +02:00
## Preparations <a id="preparations"></a>
2015-04-20 16:43:17 +02:00
2016-08-30 15:13:06 +02:00
Specify the release version.
```bash
2019-09-19 13:49:31 +02:00
VERSION=2.11.0
```
2016-08-30 15:13:06 +02:00
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
```
2018-04-24 14:51:26 +02:00
### Issues <a id="issues"></a>
2015-12-07 16:29:19 +01:00
Check issues at https://github.com/Icinga/icinga2
2018-04-24 14:51:26 +02:00
### Backport Commits <a id="backport-commits"></a>
2016-04-20 18:35:19 +02:00
2017-02-13 10:51:27 +01:00
For minor versions you need to manually backports any and all commits from the
master branch which should be part of this release.
2016-04-20 18:35:19 +02:00
2021-06-24 19:22:56 +02:00
### Windows Dependencies <a id="windows-dependencies"></a>
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
2021-06-24 19:22:56 +02:00
```
#### 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](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](https://github.com/Icinga/icinga2/blob/master/doc/21-development.md#tldr).
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/21-development.md)
* [doc/win-dev.ps1](doc/win-dev.ps1)
(also affects CI/CD)
* [tools/win32/configure.ps1](tools/win32/configure.ps1)
* [tools/win32/configure-dev.ps1](tools/win32/configure-dev.ps1)
2021-07-01 12:16:30 +02:00
#### 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.
2018-04-24 14:51:26 +02:00
## Version <a id="version"></a>
2018-09-25 17:29:23 +02:00
Update the version:
```bash
perl -pi -e "s/Version: .*/Version: $VERSION/g" ICINGA2_VERSION
```
2016-08-30 15:13:06 +02:00
2018-04-24 14:51:26 +02:00
## Changelog <a id="changelog"></a>
2019-09-19 13:49:31 +02:00
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.
2015-06-18 15:53:08 +02:00
2018-04-24 14:51:26 +02:00
## Git Tag <a id="git-tag"></a>
```bash
git commit -v -a -m "Release version $VERSION"
```
2018-04-24 14:51:26 +02:00
Create a signed tag (tags/v<VERSION>) on the `master` branch (for major
releases) or the `support` branch (for minor releases).
```bash
git tag -s -m "Version $VERSION" v$VERSION
```
2018-04-24 14:51:26 +02:00
Push the tag:
2017-11-09 13:30:33 +01:00
```bash
git push origin v$VERSION
2017-11-09 13:30:33 +01:00
```
2018-04-24 14:51:26 +02:00
**For major releases:** Create a new `support` branch:
```bash
2018-04-24 14:51:26 +02:00
git checkout master
git push
2019-07-25 09:23:28 +02:00
git checkout -b support/2.12
git push -u origin support/2.12
2018-04-24 14:51:26 +02:00
```
2019-09-19 13:49:31 +02:00
## Package Builds <a id="package-builds"></a>
```bash
2019-09-19 13:49:31 +02:00
mkdir $HOME/dev/icinga/packaging
cd $HOME/dev/icinga/packaging
```
2018-04-24 14:51:26 +02:00
### RPM Packages <a id="rpm-packages"></a>
```bash
2020-10-13 17:18:31 +02:00
git clone git@git.icinga.com:packaging/rpm-icinga2.git && cd rpm-icinga2
```
2019-09-19 13:49:31 +02:00
### DEB Packages <a id="deb-packages"></a>
2017-11-09 12:32:32 +01:00
```bash
2019-09-19 13:49:31 +02:00
git clone git@git.icinga.com:packaging/deb-icinga2.git && cd deb-icinga2
2017-11-09 12:32:32 +01:00
```
2017-11-09 13:30:33 +01:00
2021-08-02 17:08:15 +02:00
### Raspbian Packages
2018-04-23 11:28:12 +02:00
```bash
2020-10-13 17:18:31 +02:00
git clone git@git.icinga.com:packaging/raspbian-icinga2.git && cd raspbian-icinga2
2018-04-23 11:28:12 +02:00
```
2019-09-19 13:49:31 +02:00
### Windows Packages
```bash
2020-10-13 17:18:31 +02:00
git clone git@git.icinga.com:packaging/windows-icinga2.git && cd windows-icinga2
2019-09-19 13:49:31 +02:00
```
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
### Branch Workflow
2018-04-24 14:51:26 +02:00
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.
2019-09-19 13:49:31 +02:00
### Switch Build Type
2018-04-24 14:51:26 +02:00
Ensure that `ICINGA_BUILD_TYPE` is set to `release` in `.gitlab-ci.yml`. This should only be necessary after creating a
new branch.
2019-09-19 13:49:31 +02:00
```yaml
variables:
...
ICINGA_BUILD_TYPE: release
2019-09-19 13:49:31 +02:00
...
```
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
Commit the change.
```bash
git commit -av -m "Switch build type for 2.13"
2019-09-20 12:18:44 +02:00
```
2015-07-15 12:38:15 +02:00
2019-09-19 13:49:31 +02:00
#### RPM Release Preparations
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
Set the `Version`, `revision` and `%changelog` inside the spec file:
2015-07-15 12:38:15 +02:00
```
perl -pi -e "s/Version:.*/Version: $VERSION/g" icinga2.spec
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
vim icinga2.spec
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
%changelog
* Thu Sep 19 2019 Michael Friedrich <michael.friedrich@icinga.com> 2.11.0-1
- Update to 2.11.0
2018-04-24 14:51:26 +02:00
```
2019-09-19 13:49:31 +02:00
#### DEB and Raspbian Release Preparations
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
Update file `debian/changelog` and add at the beginning:
2018-04-24 14:51:26 +02:00
```
2019-09-19 13:49:31 +02:00
icinga2 (2.11.0-1) icinga; urgency=medium
2019-09-19 13:49:31 +02:00
* Release 2.11.0
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
-- Michael Friedrich <michael.friedrich@icinga.com> Thu, 19 Sep 2019 10:50:31 +0200
2018-04-24 14:51:26 +02:00
```
#### 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
```
2019-09-19 13:49:31 +02:00
### Release Commit
Commit the changes and push the branch.
```bash
2019-09-19 13:49:31 +02:00
git commit -av -m "Release $VERSION-1"
git push origin 2.11
```
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
GitLab will now build snapshot packages based on the tag `v2.11.0` of Icinga 2.
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
### Package Tests
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
In order to test the created packages you can download a job's artifacts:
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
Visit [git.icinga.com](https://git.icinga.com/packaging/rpm-icinga2)
and navigate to the respective pipeline under `CI / CD -> Pipelines`.
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
There click on the job you want to download packages from.
2019-09-19 13:49:31 +02:00
The job's output appears. On the right-hand sidebar you can browse its artifacts.
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
Once there, navigate to `build/RPMS/noarch` where you'll find the packages.
2019-09-19 13:49:31 +02:00
### Release Packages
To build release packages and upload them to [packages.icinga.com](https://packages.icinga.com)
tag the release commit and push it.
2019-10-25 09:33:03 +02:00
RPM/DEB/Raspbian:
```bash
2019-10-25 09:33:03 +02:00
git tag -s $VERSION-1 -m "Release v$VERSION-1"
git push origin $VERSION-1
```
Windows:
```bash
2019-10-25 09:33:03 +02:00
git tag -s $VERSION -m "Release v$VERSION"
git push origin $VERSION
2018-04-24 14:51:26 +02:00
```
2015-04-20 16:43:17 +02:00
2019-10-25 09:33:03 +02:00
2019-09-19 13:49:31 +02:00
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 <a id="build-infrastructure"></a>
2018-04-24 14:51:26 +02:00
2019-09-19 13:49:31 +02:00
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
2015-04-20 16:43:17 +02:00
2016-12-14 15:22:29 +01:00
* Verify package build changes for this version.
* Test the snapshot packages for all distributions beforehand.
2019-09-19 13:49:31 +02:00
Once the release repository tags are pushed, release builds
are triggered and automatically published to packages.icinga.com
2015-12-07 16:29:19 +01:00
2018-04-24 14:51:26 +02:00
## Release Tests <a id="release-tests"></a>
2015-06-17 14:22:59 +02:00
2016-04-20 18:35:19 +02:00
* Test DB IDO with MySQL and PostgreSQL.
2015-04-20 16:43:17 +02:00
* Provision the vagrant boxes and test the release packages.
* Test the [setup wizard](https://packages.icinga.com/windows/) inside a Windows VM.
2016-04-20 18:35:19 +02:00
* Start a new docker container and install/run icinga2.
2015-06-17 14:22:59 +02:00
### CentOS
2015-06-17 14:22:59 +02:00
```bash
2019-10-25 09:33:03 +02:00
docker run -ti centos:7 bash
2015-07-08 12:55:50 +02:00
yum -y install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
2019-09-19 13:49:31 +02:00
yum -y install epel-release
yum -y install icinga2
icinga2 daemon -C
```
2015-06-17 14:22:59 +02:00
2019-09-19 13:49:31 +02:00
### Ubuntu
```bash
2019-09-19 13:49:31 +02:00
docker run -ti ubuntu:bionic bash
apt-get update
apt-get -y install apt-transport-https wget gnupg
2019-09-19 13:49:31 +02:00
wget -O - https://packages.icinga.com/icinga.key | apt-key add -
2019-09-19 13:49:31 +02:00
. /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
2019-09-19 13:49:31 +02:00
echo "deb-src https://packages.icinga.com/ubuntu icinga-${DIST} main" >> \
/etc/apt/sources.list.d/${DIST}-icinga.list
2019-09-19 13:49:31 +02:00
apt-get update
apt-get -y install icinga2
2019-09-19 13:49:31 +02:00
icinga2 daemon -C
```
2019-09-19 13:49:31 +02:00
2018-04-24 14:51:26 +02:00
## GitHub Release <a id="github-release"></a>
2015-04-20 16:43:17 +02:00
2018-04-24 14:51:26 +02:00
Create a new release for the newly created Git tag: https://github.com/Icinga/icinga2/releases
2015-04-20 16:43:17 +02:00
> Hint: Choose [tags](https://github.com/Icinga/icinga2/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.
2018-04-24 14:51:26 +02:00
## Post Release <a id="post-release"></a>
### Online Documentation <a id="online-documentation"></a>
2015-04-20 16:43:17 +02:00
> Only required for major releases.
Navigate to `puppet-customer/icinga.git` and do the following steps:
#### Testing
```bash
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.
```bash
puppet agent -t --environment testing --noop
```
Once succeeded, continue with production deployment.
#### Production
```bash
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).
```bash
puppet agent -t
```
2015-04-20 16:43:17 +02:00
#### Manual Generation
SSH into the webserver or ask @bobapple.
```bash
cd /usr/local/icinga-docs-tools && ./build-docs.rb -c /var/www/docs/config/icinga2-latest.yml
```
2018-04-24 14:51:26 +02:00
### Announcement <a id="announcement"></a>
2015-04-20 16:43:17 +02:00
* Create a new blog post on [icinga.com/blog](https://icinga.com/blog) including a featured image
* Create a release topic on [community.icinga.com](https://community.icinga.com)
* Release email to net-tech & team
2015-12-07 16:29:19 +01:00
2018-04-24 14:51:26 +02:00
### Project Management <a id="project-management"></a>
2015-12-07 16:29:19 +01:00
2017-08-02 11:55:05 +02:00
* Add new minor version on [GitHub](https://github.com/Icinga/icinga2/milestones).