From 62d7e2af80d0b551ef04f08ec7dc30672d6af6ba Mon Sep 17 00:00:00 2001 From: Eric Lippmann Date: Tue, 11 Jul 2023 12:53:29 +0200 Subject: [PATCH 1/2] Replace `RELEASE.md' with issue template Apart from the Windows-related notes, all instructions are common to our releases and therefore do not need to be explicitly listed here. In addition, most of the information was severely outdated, especially with respect to how our packaging works. --- .github/ISSUE_TEMPLATE/release.md | 21 ++ RELEASE.md | 421 ------------------------------ 2 files changed, 21 insertions(+), 421 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/release.md delete mode 100644 RELEASE.md diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md new file mode 100644 index 00000000000..ef4061cd616 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/release.md @@ -0,0 +1,21 @@ +--- +name: '[INTERNAL] Release' +about: Release a version +title: 'Release Version v$version' +labels: '' +assignees: '' + +--- + +# Release Workflow + +- [ ] Check that the `.mailmap` and `AUTHORS` files are up to date +- [ ] Update `ICINGA2_VERSION` +- [ ] Update bundled Windows dependencies +- [ ] Update `CHANGELOG.md` +- [ ] Create and push a signed tag for the version +- [ ] Build and release DEB and RPM packages +- [ ] Build and release Windows packages +- [ ] Create release on GitHub +- [ ] Update public docs +- [ ] Announce release diff --git a/RELEASE.md b/RELEASE.md deleted file mode 100644 index b5290599887..00000000000 --- a/RELEASE.md +++ /dev/null @@ -1,421 +0,0 @@ -# Release Workflow - -#### Table of Content - -- [1. Preparations](#preparations) - - [1.1. Issues](#issues) - - [1.2. Backport Commits](#backport-commits) - - [1.3. Windows Dependencies](#windows-dependencies) -- [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) -- [6. Build Server](#build-infrastructure) -- [7. Release Tests](#release-tests) -- [8. GitHub Release](#github-release) -- [9. Docker](#docker) -- [10. Post Release](#post-release) - - [10.1. Online Documentation](#online-documentation) - - [10.2. Announcement](#announcement) - - [10.3. Project Management](#project-management) - -## Preparations - -Specify the release version. - -```bash -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](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) - -#### 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: - -```bash -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 - -```bash -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). - -```bash -git tag -s -m "Version $VERSION" v$VERSION -``` - -Push the tag: - -```bash -git push origin v$VERSION -``` - -**For major releases:** Create a new `support` branch: - -```bash -git checkout master -git push - -git checkout -b support/2.12 -git push -u origin support/2.12 -``` - - -## Package Builds - -```bash -mkdir $HOME/dev/icinga/packaging -cd $HOME/dev/icinga/packaging -``` - -### RPM Packages - -```bash -git clone git@git.icinga.com:packaging/rpm-icinga2.git && cd rpm-icinga2 -``` - -### DEB Packages - -```bash -git clone git@git.icinga.com:packaging/deb-icinga2.git && cd deb-icinga2 -``` - -### Raspbian Packages - -```bash -git clone git@git.icinga.com:packaging/raspbian-icinga2.git && cd raspbian-icinga2 -``` - -### Windows Packages - -```bash -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. - -```yaml -variables: - ... - ICINGA_BUILD_TYPE: release - ... -``` - -Commit the change. - -```bash -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 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 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. - -```bash -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](https://git.icinga.com/packaging/rpm-icinga2) -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](https://packages.icinga.com) -tag the release commit and push it. - -RPM/DEB/Raspbian: - -```bash -git tag -s $VERSION-1 -m "Release v$VERSION-1" -git push origin $VERSION-1 -``` - -Windows: - -```bash -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](https://packages.icinga.com/windows/) inside a Windows VM. -* Start a new docker container and install/run icinga2. - -### CentOS - -```bash -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 - -```bash -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](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. - - -## Post Release - -### Online Documentation - -> 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 -``` - -#### 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 -``` - -### Announcement - -* 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 - -### Project Management - -* Add new minor version on [GitHub](https://github.com/Icinga/icinga2/milestones). From 4164bee6c7de1199da9054f1192a679b46c28ecc Mon Sep 17 00:00:00 2001 From: "Alexander A. Klimov" Date: Wed, 12 Jul 2023 18:10:57 +0200 Subject: [PATCH 2/2] Release issue template: restore non-trivial info from removed RELEASE.md We have dedicated repositories for packages, so this stuff is already fragmented into visible and invisible. The docs can be fragmented the same way. But then everything about this repo should be documented in this repo, too. This just re-adds docs about the publicly visible stuff. Ex. the last section, but it is easy to miss, so it's here. --- .github/ISSUE_TEMPLATE/release.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md index ef4061cd616..87c1b595f1d 100644 --- a/.github/ISSUE_TEMPLATE/release.md +++ b/.github/ISSUE_TEMPLATE/release.md @@ -19,3 +19,30 @@ assignees: '' - [ ] Create release on GitHub - [ ] Update public docs - [ ] Announce release + +## Update Bundled Windows Dependencies + +### Update packages.icinga.com + +Add the latest Boost and OpenSSL versions to +https://packages.icinga.com/windows/dependencies/, e.g.: + +* https://master.dl.sourceforge.net/project/boost/boost-binaries/1.82.0/boost_1_82_0-msvc-14.2-64.exe +* https://master.dl.sourceforge.net/project/boost/boost-binaries/1.82.0/boost_1_82_0-msvc-14.2-32.exe +* https://slproweb.com/download/Win64OpenSSL-3_0_9.exe +* https://slproweb.com/download/Win32OpenSSL-3_0_9.exe + +### Update Build Server, CI/CD and Documentation + +* [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) + +### 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.