Update RELEASE.md

RELEASE.md

@@ -1,31 +1,11 @@
-# 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. Post Release](#post-release)
-  - [9.1. Online Documentation](#online-documentation)
-  - [9.2. Announcement](#announcement)
-  - [9.3. Project Management](#project-management)
-
-## Preparations <a id="preparations"></a>
+# Release Workflow
+
+## Preparations
 
 Specify the release version.
 
 ```
-VERSION=2.6.3
+VERSION=2.7.0
 ```
 
 Add your signing key to your Git configuration file, if not already there.
@@ -39,25 +19,25 @@ vim $HOME/.gitconfig
         signingkey = D14A1F16
 ```
 
-### Issues <a id="issues"></a>
+### Issues
 
 Check issues at https://github.com/Icinga/icingaweb2
 
-### Backport Commits <a id="backport-commits"></a>
+### Backport Commits
 
 For minor versions not branched off git master you need
 to manually backport any and all commits from the
 master branch which should be part of this release.
 
-### Authors <a id="authors"></a>
+### Authors
 
 Update the [.mailmap](.mailmap) and [AUTHORS](AUTHORS) files:
 
 ```
 git log --use-mailmap | grep '^Author:' | cut -f2- -d' ' | sort | uniq > AUTHORS
 ```
 
-## Version <a id="version"></a>
+## Version
 
 Update the version in the following files:
 
@@ -73,11 +53,12 @@ sed -i "s/const VERSION = '.*'/const VERSION = '$VERSION'/g" library/Icinga/Appl
 find . -type f -name '*.info' -exec sed -i "s/Version: .*/Version: $VERSION/g" {} \;
 ```
 
-## Changelog <a id="changelog"></a>
+## Changelog
 
-Link to the milestone and closed=1 as filter.
+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  <a id="git-tag"></a>
+## Git Tag
 
 ```
 git commit -v -a -m "Release version $VERSION"
@@ -93,138 +74,125 @@ git tag -s -m "Version $VERSION" v$VERSION
 Push the tag:
 
 ```
-git push --tags
+git push v$VERSION
 ```
 
 **For major releases:** Create a new `support` branch:
 
 ```
 git checkout master
-git checkout -b support/2.6
-git push -u origin support/2.6
+git checkout -b support/2.7
+git push -u origin support/2.7
 ```
 
-## Package Builds  <a id="package-builds"></a>
+## Package Builds
 
-### RPM Packages  <a id="rpm-packages"></a>
+### RPM Packages
 
 ```
-git clone git@github.com:icinga/rpm-icingaweb2.git && cd rpm-icingaweb2
+git clone git@git.icinga.com:packaging/rpm-icingaweb2.git && cd rpm-icingaweb2
 ```
 
-#### Branch Workflow
-
-**Major releases** are branched off `master`.
+### DEB Packages
 
 ```
-git checkout master && git pull
+git clone [email protected]:packaging/deb-icingaweb2.git && cd deb-icingaweb2
 ```
 
-**Bugfix releases** are created in the `release` branch and later merged to master.
+### Branch Workflow
 
-```
-git checkout release && git pull
-```
+Checkout `master` and create a new branch.
 
-#### Release Commit
+* For releases use x.x[.x] as branch name (e.g. 2.7 or 2.7.1)
+* For releases with revision use x.x.x-n (e.g. 2.7.0-2)
 
-Set the `Version`, `Revision` and `changelog` inside the spec file.
+### Switch Build Type (For RPM and DEB)
 
-```
-sed -i "s/Version: .*/Version: $VERSION/g" icingaweb2.spec
-
-vim icingaweb2.spec
+Edit file `.gitlab-ci.yml` and comment variable `ICINGA_BUILD_TYPE` out.
 
-%changelog
-* Wed Apr 24 2019 Johannes Meyer <[email protected]> 2.6.3-1
-- Update to 2.6.3
+```yaml
+variables:
+  ...
+  #ICINGA_BUILD_TYPE: snapshot
+  ...
 ```
 
+Commit the change.
+
 ```
-git commit -av -m "Release $VERSION-1"
-git push
+git commit -av -m "Switch build type for $VERSION-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.
-`git checkout master && git pull && git cherry-pick release && git push`
+#### RPM Release Preparations
 
+Set the `Version`, `revision` and `%changelog` inside the spec file:
 
-### DEB Packages  <a id="deb-packages"></a>
-
-```
-git clone [email protected]:icinga/deb-icingaweb2.git && cd deb-icingaweb2
 ```
+sed -i "s/Version:.*/Version:        $VERSION/g" icingaweb2.spec
 
-#### Branch Workflow
-
-**Major releases** are branched off `master`.
+vim icingaweb2.spec
 
-```
-git checkout master && git pull
+%changelog
+* Tue Jul 30 2019 Johannes Meyer <[email protected]> 2.7.0-1
+- Update to 2.7.0
 ```
 
-**Bugfix releases** are created in the `release` branch and later merged to master.
+#### DEB Release Preparations
+
+Update file `debian/changelog` and add at the beginning:
 
 ```
-git checkout release && git pull
-```
+icingaweb2 (2.7.0-1) icinga; urgency=medium
 
-#### Release Commit
+  * Release 2.7.0-1
 
-Set the `Version`, `Revision` and `changelog` by using the `dch` helper.
+ -- Eric Lippmann <[email protected]>  Tue, 30 Jul 2019 09:28:52 +0000
 
 ```
-VERSION=2.6.3
 
-./dch $VERSION-1 "Update to $VERSION"
-```
+### Release Commit (For RPM and DEB)
+
+Commit the changes and push the branch.
 
 ```
 git commit -av -m "Release $VERSION-1"
-git push
+git push origin 2.7
 ```
 
+Gitlab will now build snapshot packages based on the tag `v2.7.0` of Icinga Web 2.
 
-**Note for major releases**: Update release branch to latest.
+### Package Tests
 
-```
-git checkout release && git pull && git merge master && git push
-```
+In order to test the created packages you can download a job's artifacts:
 
-**Note for minor releases**: Cherry-pick the release commit into master.
+Visit [git.icinga.com](https://git.icinga.com/packaging/rpm-icingaweb2)
+and navigate to the respective pipeline under `CI / CD -> Pipelines`.
 
-```
-git checkout master && git pull && git cherry-pick release && git push
-```
+There click on the job you want to download packages from:
 
+![Pipeline Jobs](doc/res/gitlab-rpm-package-pipeline-jobs.png "Pipeline Jobs")
 
-#### DEB with dch on macOS
+The job's output appears. On the right-hand sidebar you can browse its artifacts:
 
-```
-docker run -v `pwd`:/mnt/packaging -ti ubuntu:bionic bash
+![Job Artifacts](doc/res/gitlab-job-artifacts.png "Job Artifacts")
 
-apt-get update && apt-get install git ubuntu-dev-tools vim -y
-cd /mnt/packaging
+Once there, navigate to `build/RPMS/noarch` where you'll find the packages.
 
-git config --global user.name "Eric Lippmann"
-git config --global user.email "[email protected]"
+### Release Packages
 
-VERSION=2.6.3
+To build release packages and upload them to [packages.icinga.com](https://packages.icinga.com)
+tag the release commit and push it.
 
-./dch $VERSION-1 "Update to $VERSION"
+```
+git tag -s 2.7.0-1
+git push origin 2.7.0-1
 ```
 
-## Build Server <a id="build-server"></a>
+Now cherry pick the release commit to `master` so that the changes are transferred back to it.
 
-* 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.
-  * Wait until all jobs have passed and then publish them one by one with `allow_release`
+**Attention**: Only the release commit. *NOT* the one switching the build type!
 
-## Release Tests  <a id="release-tests"></a>
+## Release Tests
 
 * Provision the vagrant boxes and test the release packages.
 * * Start a new docker container and install/run Icinga Web 2 & icingacli.
@@ -258,36 +226,34 @@ apt-get -y install icingaweb2 icingacli
 icingacli
 ```
 
-
-## GitHub Release  <a id="github-release"></a>
+## GitHub Release
 
 Create a new release for the newly created Git tag: https://github.com/Icinga/icingaweb2/releases
 
 > Hint: Choose [tags](https://github.com/Icinga/icingaweb2/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.
+Use the changelog for the release body.
 
-### Online Documentation  <a id="online-documentation"></a>
+## Online Documentation
 
 This is built with a daily cronjob.
 
-#### Manual Updates
+### Manual Updates
 
 SSH into the webserver or ask [bobapple](https://github.com/bobapple).
 
 ```
 cd /usr/local/icinga-docs-tools && ./build-docs.rb -c /var/www/docs/config/icingaweb2-latest.yml
 ```
 
-### Announcement  <a id="announcement"></a>
+## 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  <a id="project-management"></a>
+## Project Management
 
 * Add new minor version on [GitHub](https://github.com/Icinga/icingaweb2/milestones).
 * Close the released version on [GitHub](https://github.com/Icinga/icingaweb2/milestones).