h1. Release Management

For each major (x.0) and minor release there is a release manager who is responsible for making releases happen. This person is responsible for preparing for releases, ensuring stability of the release, ensuring documentation and announcements are made and generally ensuring a high quality is made.

This document describes high level tasks, while the [[Release_Process]] document covers specific steps (down to individual commands) that need to be run at each step of the release.

{{toc}}

h2. Version numbering

Foreman version numbers are in the form: MAJOR1.MAJOR2.MINOR, with an optional -RC1 suffix for release candidates.

A "major" release is a new 1.8, 1.9 etc.  A minor release would be 1.8.1.  A release candidate would be 1.8.0-RC1.

There is no plan for when to increment the first digit of the major version number.  Perhaps if a large enough refactoring is made to Foreman's design, it could be raised on foreman-dev and the number changed.

h2. Schedule

The aim is to make a Foreman major release every three months, with around 3-5 minor releases every month thereafter.  In reality this varies between 3-5 months for a major, and 2-6 weeks for a minor.  This is a time-based and not feature-based release strategy, more on that below.

For each major release, create a new schedule linked from [[Development_Resources]].  Keep this up to date as and when any branching and release dates are known.

Generally the landmark events for a release "N" are, with example dates:

# 1st January: Development starts for N, when N-1 is branched

#* i.e. commits go to develop branches only

# _1st February: N-1 is released, therefore N is released in 3 months' time_

# 1st March: branch warning

# 1st April: N is branched and N.0-RC1 made

# 15th April: N.0-RC2 is made

# 1st May: N.0 is released

# 1st June: N.1 is released

!release_schedule.png!

Clearly there are many release streams running in parallel at any one time.  Unfortunately we don't have an automatic visualisation of this.

The biggest risks to the schedule order tend to be, a) delays to branch usually caused by requests for specific features, b) elongated release candidate period due to regressions.

h3. Time-based releases and feature inclusion

Major releases are only time-based, as the project makes no attempt to produce a roadmap for feature inclusion (such processes can take months).  Simply, whatever is merged at the time of branching are the features that make the release.

Requests for additional features to be included in the release are common between branching and RC1, but should be considered on a case-by-case basis, preferring to refuse the request.  They have the risk of adding instability to the release, as it can take days or weeks to discover issues caused by the change affecting other components.

h3. Release candidates

Typically between two and four release candidates are made, starting from about one week after branching with a spacing of two weeks.  This leads to a typical RC period of between 1-2 months.

When more than two RCs are required, the schedule will likely have a knock-on effect for the subsequent major release.  Aim to release N+1 three months after N.0 still - so the N release process may be four months, but aim for N+1 to be three months after, rather than two months.

h3. Minor releases

Typically between three and five minor releases are made, starting from about 2-3 weeks after the major release and a spacing of around one month between minors.  This leads to an overall lifecycle of about 4-6 months for a single major release.

The first minor tends to follow the major release quickly, as further regressions are normally found and need to be addressed soon.  Minor releases 2 and 3 tend to continue with regression fixes and may contain general bug fixes found in parallel and that are safe and good to backport.

Minor releases 4 and 5 usually only happen in response to high severity security issues that can be safely fixed.

Releases typically go out of support once 2 newer releases are released (e.g., 1.18 goes out of support once 1.20 is released), though there may be additional minor releases done afterwards if critical issues are discovered.

h2. Issue tracking

Redmine is the primary issue tracker for Foreman core projects, where all commits to the "big four" (Foreman, proxy, installer, SELinux) must have a corresponding ticket.  This ensures that the release manager can track changes for release notes and backports.

Every closed ticket should have the "Release" flag set on commit, preferably by the release manager.

# If it contains a refactoring, set it to the next major release

# If it is a new feature, set it to the next major release

# If it fixes a regression for something only in develop, set it to the next major release...

#* ..though if it was scheduled for an upcoming release but then got moved to a later one, consider moving both back to the upcoming release

# If it depends on another ticket or new dependency, set it to the next major release

# If it contains a database schema change, set it to the next major release

# If it contains new strings or changes, set it to the next major release

# If it is a bug fix that contains no tests, set it to the next major release

# If it is a bug fix that contains a behaviour change likely to require some adaption, set it to the next major release

# If it is a bug fix that is well-tested and seems low risk, set it to the next minor release

# If it is a high severity security fix, set it to the next minor release

These aren't hard and fast rules, make decisions based on experience.  If in doubt, defer it to the next major release.

When a regression is found - that is, a negative behaviour change between the last release and the upcoming one:

# Mark the ticket as related to the ticket that caused the regression

# If the change causing it is not in a stable branch yet, set both tickets to the next major release

# Set the release flag to the upcoming release

Any open ticket with a release set is a blocker.

h2. Components

Some release components are pieces of software that the project will maintain and ship (Foreman core, smart proxy etc), while others may be maintained by third parties.  In order to release, we need to try and ensure as much of this is working correctly with the release as possible.

# "Foreman":https://github.com/theforeman/foreman

#* branched and released as part of the release process

#* high level of activity, has a reasonably stable develop branch

#* blockers tracked in Redmine where "Release = X"

# "Smart proxy":https://github.com/theforeman/smart-proxy

#* branched and released as part of the release process

#* low-medium level of activity, generally has a stable develop branch

#* blockers tracked in Redmine's smart-proxy project where "Release = X"

# "Foreman SELinux":https://github.com/theforeman/foreman-selinux

#* branched and released as part of the release process

#* very low level of activity, generally has a stable develop branch

#* blockers tracked in Redmine's foreman-selinux project where "Release = X"

# "Puppet modules":https://github.com/theforeman/?utf8=%E2%9C%93&query=puppet

#* new major/minor releases immediately prior to Foreman releases, patch releases where required

#* releases generally made from master or -stable branches when necessary

#* low-high levels of activity, generally has a stable master branch

#* blockers usually tracked in Redmine's puppet-foreman project where "Release = X"

# "Foreman Installer":https://github.com/theforeman/foreman-installer

#* branched and released as part of the release process

#* composed of Puppet modules above

#* very low level of activity itself, generally has a stable develop branch

#* blockers tracked in Redmine's puppet-foreman project where "Release = X"

# "Debian packaging":https://github.com/theforeman/foreman-packaging/tree/deb/develop

#* branched and released as part of the release process

#* low-medium level of activity itself, generally has a stable develop branch

#* blockers tracked in Redmine's rpms project where "Release = X"

# "RPM packaging":https://github.com/theforeman/foreman-packaging/tree/rpm/develop

#* branched and released as part of the release process

#* medium level of activity itself, generally has a stable develop branch

#* blockers tracked in Redmine's rpms project where "Release = X"

# "Hammer CLI":https://github.com/theforeman/hammer-cli

#* branched and released in parallel to the release process

#* medium level of activity itself, generally has a stable develop branch

#* blockers tracked in Redmine's hammer-cli project

# "Plugins":http://projects.theforeman.org/projects/foreman/wiki/List_of_Plugins

#* active and larger plugins tend to be branched and released for new major Foreman versions

#* asynchronous release schedules, try to request any compatibility releases are done by the RC1-RC2 timeframe

#* blockers tracked in per-project issue trackers, either Redmine or GitHub

# "theforeman.org":https://github.com/theforeman/theforeman.org

#* copied and updated during the release process

#* medium level of activity itself

#* blockers tracked in per-release "tickets on GitHub":https://github.com/theforeman/theforeman.org/issues

# "Translations":https://www.transifex.com/projects/p/foreman/

#* updated during the release process, between branching and the .2 release

#* medium level of activity itself

#* issues tracked in Transifex per-translation

#* can only translate one release at a time, usually switches after the .2 release to the next major

h2. Comments

The current release process has been developed over a few years, over half a dozen major releases and many tens of minor releases.  Suggestions for changes are welcome, please propose them to "the development forum":https://community.theforeman.org/c/development.