h1. Release Process

For each major release (i.e. not patch releases), the project selects a "release nanny" who's responsible for taking the develop branch through to release.

Please amend these lists as you see free, and as you find what works and what doesn't work.

h2. First steps

# Select the release nanny

# Ensure RPM and Debian nightly packages are in good shape and all RPM dependencies are up to date

# Ensure "Transifex project":https://www.transifex.com/projects/p/foreman/ is up to date

# Decide on the version number

# If number has changed, update version number in redmine

# Add _next+1_ anticipated version number to redmine under "Releases":http://projects.theforeman.org/rb/releases/foreman, sharing "With subprojects"

# Check "roadmap":http://projects.theforeman.org/projects/foreman/roadmap and issue search ("example":http://projects.theforeman.org/projects/foreman/issues?fixed_version_id=24&set_filter=1&status_id=o)

#* reassign major features to next+1 version or remove version

#* assign relevant bugs to this upcoming release

#* multiple bugs can be managed using checkboxes and then right clicking on the boxes for a menu

#* create public custom query with target version set, sorted by status ascending, then priority descending

# Go through targeted features in redmine and align features with our "backlog":https://trello.com/board/foreman-backlog/5162af6bb868365e0c007135

h2. Before creating branch in git

# Announce beginning of bug-squashing to foreman-dev ("example":http://groups.google.com/group/foreman-dev/browse_thread/thread/769d9060774da864)

# Copy website manual content ("theforeman.org repo":http://github.com/theforeman/theforeman.org) from previous version to this version ("example":https://github.com/theforeman/theforeman.org/pull/43)

# Update manual if applicable for any additional installation steps

# Draft release notes in markdown ("example":https://gist.github.com/domcleal/5567450) using roadmap, with these sections (and do not use personal pronouns):

## Headline features: half a dozen important features with a few sentences description each

## Upgrade notes: all important notices that users must be aware of before upgrading

## Release notes: bullet point list by category of most changes, excluding bug fixes for issues introduced during the release cycle, include link to bug numbers (helper vim search and replace command bellow)

# Check @git log@ for any changes without associated bug number and add to release notes if applicable (https://gist.github.com/lzap/6520535)

# Refresh kickstart, snippet and partition table templates from the community-templates repo to Foreman core

# Request creation of tags and build targets in "Koji":http://koji.katello.org/koji from rel-eng:

#* foreman-1.2-rhel6 etc. as clones of nightly tags

#* foreman-plugins-1.2-rhel6 etc. with inheritance from the new Foreman tags

#* example set of actions: http://pastebin.test.redhat.com/162144 and http://pastebin.test.redhat.com/162145

#* Untag all git/nightly builds: @for t in foreman-1.2-rhel6 foreman-1.2-nonscl-rhel6 foreman-1.2-rhel7 foreman-1.2-nonscl-rhel7 foreman-1.2-fedora19; do kkoji list-tagged $t  | grep git | awk '{print $1}' | xargs kkoji untag-build  $t; done@

#* check for non-SCL packages that might be in the SCL tags and untag them, else these will cause mash precedence issues

# Create mash scripts and configuration on Koji

#* copy /usr/local/bin/foreman-mash-split-1.*.py to foreman-mash-split-1.2.py, update the OSes and version numbers at the bottom

#* copy /etc/mash/foreman-1.*-*.mash, update the version numbers, add/remove files for OS changes

#* update /etc/mash/foreman-1.2-*.mash with GPG key ID

# Add new lookaside repos to foreman-packaging/rpm/develop, repoclosure/yum_*.conf

# Add new plugin tags (i.e. 1.2) to Koji plugins mash script (foreman-mash-split-plugins.py)

# Add version (1.2) to "release_plugins_push":http://ci.theforeman.org/view/Release jobs/job/release_plugins_push job (note, it will be added to tests later)

# Add release to "Found in release" list in redmine: http://projects.theforeman.org/custom_fields/4/edit

Helper vim command to replace all @(#1234)@ bugs with links:

    %s/(\(#\)\([0-9]\+\))/(\[\1\2]\(http:\/\/projects.theforeman.org\/issues\/\2))/g

h2. Pre-release candidates

When ready to branch for release candidates.

# Add new languages that are at a reasonable completion on Transifex to *develop*

# In foreman *develop* run @make -C locale tx-update@

# In foreman, smart-proxy, foreman-installer and foreman-selinux branch *develop* to *1.2-stable* (*from this point* cherry-picks into this branch only from this point using: @git cherry-pick -x SHA@)

# In foreman-installer, branch *1.2-stable*, 

## change Puppetfile from git references to specific version ranges (e.g. @>= 1.3.1 < 1.4.0@)

# In foreman *develop* commit with message "Bump version to 1.3-develop":

## change to VERSION to 1.3.0-develop

## run @extras/changelog@

# In smart-proxy *develop* commit with message "Bump version to 1.3-develop":

## change to VERSION to 1.3.0-develop

## run @extra/changelog@

# In foreman-selinux *develop* commit with message "Bump version to 1.3-develop":

## change to VERSION to 1.3.0-develop

## run @extras/changelog@

# In foreman-installer *develop* commit with message "Bump version to 1.3-develop":

## change to VERSION to 1.3.0-develop

# In foreman-packaging, branch *rpm/develop* to *rpm/1.2*, then on rpm/1.2:

## in rel-eng/releasers.conf and rel-eng/tito.props, replace "nightly" with "1.2"

# In foreman-packaging/rpm/develop, change foreman/foreman-proxy/foreman-installer/foreman-selinux version to 1.3.0, add %changelog entry

# In foreman-packaging/deb/develop, change foreman/foreman-proxy/foreman-installer version to 1.3.0 via a changelog entry

# Update foreman-dev with "translations status":https://www.transifex.com/projects/p/foreman/ to encourage 100% translations before release, announce string freeze date

# Change Transifex resource URL to point to the 1.2-stable branch

# Set up test_1_2_stable job on Jenkins, copy from existing stable or test_develop (don't use dots in the name, it breaks)

# Update release notes in new website manual version

# Generate a release GPG key using [[GPG_Keys]] and publish to keyserver & security.md on the website

h2. For each release candidate

# Compare tagged packages in nightly vs. release koji tag and re-tag any updated dependencies that are required

# In foreman *1.2-stable* run @make -C locale tx-update@

# In foreman *1.2-stable* commit with message "Release 1.2.0-RC1":

## change VERSION to 1.2.0-RC1

## run @extras/changelog@

# In smart-proxy *1.2-stable* commit with message "Release 1.2.0-RC1":

## change VERSION to 1.2.0-RC1

## run @extra/changelog@

# In foreman-selinux *1.2-stable* commit with message "Release 1.2.0-RC1":

## change VERSION to 1.2.0-RC1

## run extras/changelog

# In foreman-installer *1.2-stable* commit with message "Release 1.2.0-RC1":

## change VERSION to 1.2.0-RC1

# Tag commits in foreman, smart-proxy, foreman-installer and foreman-selinux: @git tag -m "Release 1.2.0-RC1" 1.2.0-RC1@

# Push to the project repos: @git push project && git push project 1.2.0-RC1@

# Run the Jenkins "Release Pipeline":http://ci.theforeman.org/view/Release%20pipeline/ to create tarballs

# Verify tarballs are present on downloads.theforeman.org, download, sign and upload detached signatures

## @gpg --homedir gnupg/1.2 -b -u packages@theforeman.org foreman-1.2.0-RC1.tar.bz2@ (requires 1.2 release GPG key generated above)

# In foreman-packaging rpm/1.2 branch, change foreman.spec, foreman-proxy.spec, foreman-selinux.spec, foreman-installer.spec:

## set version to "1.2.0", release to "0.1%{?dotalpha....", uncomment alphatag* (replace # with %), change to RC1

## change @foreman/foreman.repo@ URLs from @/nightly@ to @/releases/1.2@, change "nightly" in name to "1.2" and enable gpg checking

## change @foreman/foreman-plugins.repo@ URLs from @/plugins/nightly@ to @/plugins/1.2@, change "nightly" in name to "1.2" and DO NOT enable GPG checking

## update @foreman/foreman.gpg@ with the release public key

## in each package dir, run @spectool -g *.spec@ and @git annex add *.tar.bz2@

## commit with message "Release 1.2.0-RC1"

## perform RPM scratch build of each project (see [[RPM_Packaging]])

## tag each project with @tito tag --keep-version --auto-changelog-message "Release 1.2.0-RC1"@

# [[Debian_Packaging#foreman]]: Update build.sh and changelog files with appropriate data

# Trigger next step of release pipeline: @release_packages@

#* use [[RPM_Packaging]] for the signing steps

# Update theforeman.org sections:

## @_includes/social.html@ version number

## @_includes/header.html@ manual links

# Follow "Publishing releases" below

h2. For final release

# Update version and dependency versions in all foreman-installer submodules (TODO: script this)

# Update submodules on foreman-installer's *develop* branch via PR, cherry-pick down to *1.2-stable*

# Compare tagged packages in nightly vs. release koji tag and re-tag any updated dependencies that are required

# In foreman *1.2-stable* run @make -C locale tx-update@

# In foreman *1.2-stable* commit with message "Release 1.2.0":

## change to VERSION to 1.2.0

## change foreman.spec version to "1.2.0", release to "1", add %changelog entry

## run @extras/changelog@

## change @extras/packaging/rpm/sources/foreman.repo@ URL from @/rc@ to @/releases/1.2@, change "RC" in name to "1.4" and make sure gpgcheck is on

# In smart-proxy *1.2-stable* commit with message "Release 1.2.0":

## change to lib/proxy.rb VERSION to 1.2.0

## change foreman-proxy.spec version to "1.2.0", release to "1", add %changelog entry

## run @extra/changelog@

# In foreman-selinux *1.2-stable* commit with message "Release 1.2.0":

## change foreman-selinux.spec version to "1.2.0", release to "1", comment alphatag* (replace % with #), add %changelog entry

## run extras/changelog

# In foreman-installer *1.2-stable* commit with message "Release 1.2.0":

## change foreman-installer.spec version to "1.2.0", release to "1", comment alphatag* (replace % with #), add %changelog entry

# Tag commits in foreman, smart-proxy, foreman-installer and foreman-selinux: @git tag -m "Release 1.2.0" 1.2.0@

# Push to *your* GitHub repo to enable testing first

# Perform RPM scratch build of foreman, foreman-installer, foreman-proxy and foreman-selinux (see [[RPM_Packaging]])

## if they fail, revert your branch to current @project/1.2-stable@ branch, fix the issue in your repo and retry until it works

# Push to the project repo: @git push project && git push project 1.2.0@

# [[RPM_Packaging]]: follow release procedure for foreman, foreman-proxy, foreman-installer and foreman-selinux using Jenkins

# [[Debian_Packaging#foreman]]: Update build.sh and changelog files with appropriate data

# Build foreman-installer modules from 1.2-stable (see [[Installer_Packaging]] workflow)

# Build foreman-installer Debian package from 1.2-stable (see [[Debian_Packaging#foreman-installer]])

# Update theforeman.org sections:

## @_includes/social.html@ version number

## @_includes/header.html@ manual links

## @_layouts/homepage.html@ quickstart link

## @_layouts/manual.html@ latestversion

## @_config.yml@ quickstart link

# Generate and sign tarball of foreman and smart-proxy:

## @git archive --prefix=foreman-1.2.0/ 1.2.0 | bzip2 -9 > foreman-1.2.0.tar.bz2@

## @gpg -b -u packages@theforeman.org foreman-1.2.0.tar.bz2@ (requires packages key)

# Merge develop branches into master (@git merge -Xtheirs --no-ff@) for: foreman, smart-proxy, foreman-installer, foreman-selinux

# Follow "Publishing releases" below

h2. Publishing releases (RCs and final)

# First RC: symlink @releases/1.2@ to @../rc@ inside yum.theforeman.org

# Final only: remove @releases/1.2@ symlink

# Sign all RPMs (see [[RPM_Packaging]])

# Run or request (from rel-eng) RPM repo mash/compose for Koji release tags

# Do a dry run of the RPM push process to check repoclosure etc. (see [[RPM_Packaging]])

# Push RPMs to repo on the web host, under @/rc@ or @/releases/1.2@ etc using Jenkins (see [[RPM_Packaging]])

# Push foreman-installer to Freight (see [[Debian_Packaging#foreman-installer]])

# Upload tarballs and detached signatures to http://projects.theforeman.org/projects/foreman/files

## Final only: delete all existing RC files to free up space

# Upload all installer module .tar.gz files to Puppet Forge

# Final only: update @$latest@ class parameter on @web@ class to point to the new version number (see @foreman-infra/puppet/modules/web/manifests/init.pp@)

# First RC: add version (1.2) to "release_plugins_test":http://ci.theforeman.org/view/Release jobs/job/release_plugins_test job

# Send announcement e-mail to foreman-announce, CC foreman-users, set reply-to to foreman-users

# Link to announcement e-mail on IRC, Google+ and update IRC /topic

# Update Wikipedia Foreman entry at: https://en.wikipedia.org/wiki/Foreman_(software)

# Add release to "Found in release" list in redmine: http://projects.theforeman.org/custom_fields/4/edit

h2. After final release

# Sync translations from Transifex into *develop* and run @rake locale:find@

# Remove target version from all issues assigned to the current release, unless they will be fixed in a future point release