Merge pull request #6577 from Icinga/fix/setup-api-including-users-file

[icinga2] / RELEASE.md

diff --git a/RELEASE.md b/RELEASE.md
index 0657dbb32c40f18dce3f4f360945f9fdde5a8775..89c7c9df9b73d767b313149f6ffb332deb756216 100644 (file)
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -1,43 +1,77 @@
-# Release Workflow
+# Release Workflow <a id="release-workflow"></a>
+
+#### Table of Content
+
+- [1. Preparations](#preparations)
+  - [1.1. Issues](#issues)
+  - [1.2. Backport Commits](#backport-commits)
+  - [1.3. Authors](#authors)
+- [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-server)
+- [7. Release Tests](#release-tests)
+- [8. GitHub Release](#github-release)
+- [9. Chocolatey](#chocolatey)
+- [10. Post Release](#post-release)
+  - [10.1. Online Documentation](#online-documentation)
+  - [10.2. Announcement](#announcement)
+  - [10.3. Project Management](#project-management)
+
+## Preparations <a id="preparations"></a>

 
 Specify the release version.
 
 ```
 
 Specify the release version.
 
 ```

-VERSION=2.7.1
+VERSION=2.10.2

 ```
 
 ```
 

-## Issues
+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 <a id="issues"></a>

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

-## Backport Commits
+### Backport Commits <a id="backport-commits"></a>

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

-## Authors
+### Authors <a id="authors"></a>

 
 Update the [.mailmap](.mailmap) and [AUTHORS](AUTHORS) files:
 
 ```
 git checkout master
 
 Update the [.mailmap](.mailmap) and [AUTHORS](AUTHORS) files:
 
 ```
 git checkout master

-git log --use-mailmap | grep ^Author: | cut -f2- -d' ' | sort | uniq > AUTHORS
+git log --use-mailmap | grep '^Author:' | cut -f2- -d' ' | sort | uniq > AUTHORS

 ```
 
 ```
 

-## Version
+## Version <a id="version"></a>

 
 

-Fetch the latest spec file from the [icinga-packaging](https://github.com/icinga/icinga-packaging)
-repository and verify that the latest version is set.
+Update the version:

 
 ```
 
 ```

-wget -O icinga2.spec https://raw.githubusercontent.com/Icinga/icinga-packaging/rpm/snapshot/icinga2/icinga2.spec
-gsed -i "s/Version: .*/Version: $VERSION/g" icinga2.spec
+sed -i "s/Version: .*/Version: $VERSION/g" VERSION

 ```
 
 ```
 

-## Changelog
+## Changelog <a id="changelog"></a>

 
 Update the [CHANGELOG.md](CHANGELOG.md) file.
 
 
 Update the [CHANGELOG.md](CHANGELOG.md) file.
 

+### Requirements
+

 Export these environment variables:
 
 ```
 Export these environment variables:
 
 ```


@@ -46,6 +80,10 @@ export ICINGA_GITHUB_AUTH_TOKEN='token'
 export ICINGA_GITHUB_PROJECT='icinga/icinga2'
 ```
 
 export ICINGA_GITHUB_PROJECT='icinga/icinga2'
 ```
 

+### Generation
+
+**Close the version on [GitHub](https://github.com/Icinga/icinga2/milestones).**
+

 Run the script which updates the [CHANGELOG.md](CHANGELOG.md) file.
 
 ```
 Run the script which updates the [CHANGELOG.md](CHANGELOG.md) file.
 
 ```


@@ -53,74 +91,184 @@ Run the script which updates the [CHANGELOG.md](CHANGELOG.md) file.
 git diff
 ```
 
 git diff
 ```
 

-## Git Tag
+## Git Tag  <a id="git-tag"></a>

 
 

-Commit these changes to the "master" branch:
+> **Major Releases**: Commit these changes to the `master` branch.
+>
+> **Minor Releases**: Commit changes to the `support` branch.

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

-For minor releases: Cherry-pick this commit into the "support" branch.
+Create a signed tag (tags/v<VERSION>) on the `master` branch (for major
+releases) or the `support` branch (for minor releases).
+
+```
+git tag -s -m "Version $VERSION" v$VERSION
+```

 
 

-Create a signed tag (tags/v<VERSION>) on the "master" branch (for major
-releases) or the "support" branch (for minor releases).
+Push the tag:
+
+```
+git push --tags
+```

 
 

-GB:
+**For major releases:** Create a new `support` branch:

 
 ```
 
 ```

-git tag -u EE8E0720 -m "Version $VERSION" v$VERSION
+git checkout master
+git push
+
+git checkout -b support/2.11
+git push -u origin support/2.11

 ```
 
 ```
 

-MF:
+**For minor releases:** Push the support branch, cherry-pick the release commit
+into master and merge the support branch:

 
 ```
 
 ```

-git tag -u D14A1F16 -m "Version $VERSION" v$VERSION
+git push -u origin support/2.10
+git checkout master
+git cherry-pick support/2.10
+git merge --strategy=ours support/2.10
+git push origin master

 ```
 
 ```
 

-Push the tag.
+## Package Builds  <a id="package-builds"></a>
+
+### RPM Packages  <a id="rpm-packages"></a>

 
 ```
 
 ```

-git push --tags
+git clone git@github.com:icinga/rpm-icinga2.git && cd rpm-icinga2

 ```
 
 ```
 

-For major releases: Create a new "support" branch:
+#### Branch Workflow
+
+**Major releases** are branched off `master`.

 
 ```
 
 ```

-git checkout master
-git checkout -b support/2.7
-git push -u origin support/2.7
+git checkout master && git pull

 ```
 
 ```
 

-For minor releases: Push the support branch, cherry-pick the release commit
-into master and merge the support branch:
+**Bugfix releases** are created in the `release` branch and later merged to master.

 
 ```
 
 ```

-git push -u origin support/2.7
-git checkout master
-git cherry-pick support/2.7
-git merge --strategy=ours support/2.7
-git push origin master
+git checkout release && git pull
+```
+
+#### Release Commit
+
+Set the `Version`, `Revision` and `changelog` inside the spec file.
+
+```
+sed -i "s/Version: .*/Version: $VERSION/g" icinga2.spec
+
+vim icinga2.spec
+
+%changelog
+* Tue Jul 17 2018 Michael Friedrich <michael.friedrich@icinga.com> 2.9.0-1
+- Update to 2.9.0
+```
+
+```
+git commit -av -m "Release 2.9.0-1"
+git push
+```
+
+**Note for major releases**: Update release branch to latest.
+
+```
+git checkout release && git pull && git merge master && git push
+```
+
+**Note for minor releases**: Cherry-pick the release commit into master.
+
+```
+git checkout master && git pull && git cherry-pick release && git push
+```
+
+
+### DEB Packages  <a id="deb-packages"></a>
+
+```
+git clone git@github.com:icinga/deb-icinga2.git && cd deb-icinga2
+```
+
+#### Branch Workflow
+
+**Major releases** are branched off `master`.
+
+```
+git checkout master && git pull
+```
+
+**Bugfix releases** are created in the `release` branch and later merged to master.
+
+```
+git checkout release && git pull
+```
+
+#### Release Commit
+
+Set the `Version`, `Revision` and `changelog` inside the spec file.
+
+```
+./dch 2.9.0-1 "Update to 2.9.0"
+```
+
+```
+git commit -av -m "Release 2.9.0-1"
+git push
+```
+
+```
+git commit -av -m "Release 2.9.0-1"
+```
+
+**Note for major releases**: Update release branch to latest.
+

 ```
 ```

+git checkout release && git pull && git merge master && git push
+```
+
+**Note for minor releases**: Cherry-pick the release commit into master.

 
 

-# External Dependencies
+```
+git checkout master && git pull && git cherry-pick release && git push
+```
+
+#### DEB with dch on macOS
+
+```
+docker run -v `pwd`:/mnt/packaging -ti ubuntu:xenial bash

 
 

-## Build Server
+apt-get update && apt-get install git ubuntu-dev-tools vim -y
+cd /mnt/packaging
+
+git config --global user.name "Michael Friedrich"
+git config --global user.email "michael.friedrich@icinga.com"
+
+./dch 2.10.0-1 "Update to 2.10.0"
+```
+
+
+## Build Server <a id="build-server"></a>

 
 * Verify package build changes for this version.
 * Test the snapshot packages for all distributions beforehand.
 * Build the newly created Git tag for Debian/RHEL/SuSE.
 
 * Verify package build changes for this version.
 * Test the snapshot packages for all distributions beforehand.
 * Build the newly created Git tag for Debian/RHEL/SuSE.

-* Build the newly created Git tag for Windows.
+  * Wait until all jobs have passed and then publish them one by one with `allow_release`
+* Build the newly created Git tag for Windows: `refs/tags/v2.10.0` as source and `v2.10.0` as package name.

 
 

-## Release Tests
+## Release Tests  <a id="release-tests"></a>

 
 * 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.
 
 * 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.
 
 * Start a new docker container and install/run icinga2.
 

-Example for CentOS7:
+### CentOS

 
 ```
 docker run -ti centos:latest bash
 
 ```
 docker run -ti centos:latest bash


@@ -130,57 +278,94 @@ yum -y install icinga2
 icinga2 daemon -C
 ```
 
 icinga2 daemon -C
 ```
 

-## GitHub Release
+### Debian
+
+```
+docker run -ti debian:stretch bash
+
+apt-get update && apt-get install -y wget curl gnupg apt-transport-https

 
 

-Create a new release for the newly created Git tag.
-https://github.com/Icinga/icinga2/releases
+DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
+ echo "deb http://packages.icinga.com/debian icinga-${DIST} main" > \
+ /etc/apt/sources.list.d/${DIST}-icinga.list
+ echo "deb-src http://packages.icinga.com/debian icinga-${DIST} main" >> \
+ /etc/apt/sources.list.d/${DIST}-icinga.list
+
+curl https://packages.icinga.com/icinga.key | apt-key add -
+apt-get -y install icinga2
+icinga2 daemon
+```

 
 

-## Chocolatey
+## GitHub Release  <a id="github-release"></a>
+
+Create a new release for the newly created Git tag: https://github.com/Icinga/icinga2/releases
+
+## Chocolatey  <a id="chocolatey"></a>

 
 Navigate to the git repository on your Windows box which
 already has chocolatey installed. Pull/checkout the release.
 
 
 Navigate to the git repository on your Windows box which
 already has chocolatey installed. Pull/checkout the release.
 

-Create the nupkg package:
+Create the nupkg package (or use the one generated on https://packages.icinga.com/windows):

 
 ```
 cpack
 ```
 
 
 ```
 cpack
 ```
 

-Install the created icinga2 package locally:
+Fetch the API key from https://chocolatey.org/account and use the `choco push`
+command line.

 
 ```
 
 ```

-choco install icinga2 -version 2.7.0 -fdv "%cd%" -source "'%cd%;https://chocolatey.org/api/v2/'"
+choco apikey --key xxx --source https://push.chocolatey.org/
+
+choco push Icinga2-v2.10.0.nupkg --source https://push.chocolatey.org/

 ```
 
 ```
 

-Upload the package to [chocolatey](https://chocolatey.org/packages/upload).

 
 

-## Online Documentation
+## Post Release  <a id="post-release"></a>

 
 

-Edit `config.yml` in the [icinga-docs-tools](https://github.com/Icinga/icinga-docs-tools) repository:
+### Online Documentation  <a id="online-documentation"></a>
+
+Navigate to `puppet-customer/icinga.git` and do the following steps:
+
+#### Testing

 
 ```
 
 ```

-git clone git@github.com:Icinga/icinga-docs-tools.git
-cd icinga-docs-tools/
-vim config.yml
+git checkout testing && git pull
+vim files/var/www/docs/config/icinga2-latest.yml
+
+git commit -av -m "icinga-web1: Update docs for Icinga 2"
+
+git push
+```
+
+SSH into icinga-web1 and do a manual Puppet dry run with the testing environment.

 
 

-git commit -av -m "Update to Icinga 2 v$VERSION"
+```
+puppet agent -t --environment testing --noop
+```
+
+Once succeeded, continue with production deployment.
+
+#### Production
+
+```
+git checkout master && git pull
+git merge testing

 git push
 ```
 
 git push
 ```
 

-SSH into the web VM and build the docs:
+SSH into icinga-web1 and do a manual Puppet run from the production environment (default).

 
 ```
 
 ```

-cd /var/www/docs/icinga-docs/latest/
-/usr/bin/bundle exec ./build-docs.rb
+puppet agent -t

 ```
 
 ```
 

-## Announcement
+### Announcement  <a id="announcement"></a>

 
 

-* Create a new blog post on www.icinga.com/blog
-* Social media: [Twitter](https://twitter.com/icinga), [Facebook](https://www.facebook.com/icinga), [G+](https://plus.google.com/+icinga), [Xing](https://www.xing.com/communities/groups/icinga-da4b-1060043), [LinkedIn](https://www.linkedin.com/groups/Icinga-1921830/about)
+* Create a new blog post on icinga.com/blog
+* Social media: [Twitter](https://twitter.com/icinga), [Facebook](https://www.facebook.com/icinga), [Xing](https://www.xing.com/communities/groups/icinga-da4b-1060043), [LinkedIn](https://www.linkedin.com/groups/Icinga-1921830/about)

 * Update IRC channel topic
 
 * Update IRC channel topic
 

-# After the release
+### Project Management  <a id="project-management"></a>

 
 * Add new minor version on [GitHub](https://github.com/Icinga/icinga2/milestones).
 
 * Add new minor version on [GitHub](https://github.com/Icinga/icinga2/milestones).

-* Close the released version on [GitHub](https://github.com/Icinga/icinga2/milestones).