CiviCRM Release Management

This project supports documentation and meta-activities for release-management.

Release Plans

Release Lifecycle

Each period has a different policy on accepting changes:

• During the Development/Alpha period, changes are accepted on the master branch. These are usually bugfixes, API improvements, small features, etc -- but anything that passes the review process may be accepted. The branch is internally numbered as 5.x.alpha1.
• During the RC/Beta period, a new branch (e.g. 5.0 or 5.1 or 5.2) is created. There is a general freeze on scope. However, fixes for recent regressions may still be accepted, and they will merge-forward to master. The branch is internally numbered as 5.x.beta1. (In some unusual circumstances, it could be incremented to 5.x.beta2, etc.)
• On the Release Date, the 5.x.0 version is tagged and released.
• During the Stable period, patches are not generally accepted, and there is no automatic merging. There may be patches in the following cases:
  • If a recent regression is fixed and approved for the concurrent RC/beta, then it may be back-ported to the stable. These fixes are generally released ASAP, but this is left to the discretion the maintenance/release teams.
  • The security team may approve patches for a security release. Security releases may only be published on the first or third Wednesday of the month (US/Pacific time).
  • If there are any subsequent updates, they will increment the third digit (5.x.1, 5.x.2, etc).
• Some Stable periods are extended through the Extended Security Release program, during which:
  • (Generally) Only security-fixes will be backported to ESR.
  • (Rare cases) A critical regression-fix or a security feature may be backported to ESR.

During the lifecycle, key changes come with updating the version number (tools/bin/scripts/set-version.php), making branches, and tagging releases. To understand sequencing of these steps, review an example workflow (numbers circa 5.10).

(For historical planning information from 4.7.x cycles, see 4.7-release-history.md.)

Timing

General rules:

• Standard release dates arise on the first Wed of the month.
• Dates are construed in US/Pacific time. Thus, a release on 7-Apr-21 (US/Pacific) may also viewed as 8-Apr-21 (AU/Eastern).
• All three main branches (development, RC, stable) are updated on the same day.
• Month-long periods are bounded by release dates (ie first Wed). Thus, the 5.3.x development period (May 2018) actually lasts from 2-May-18 to 6-Jun-18.
• A new ESR is designated every 6 months. ESR periods are back-to-back. The previous ESR remains active until the next ESR begins.

Those rules are not absolute -- exceptions may arise a couple times a year. For example:

• If the first Wed of a month coincides with major holiday (e.g. New Years Day), then it could be moved.
• If there's an important patch in development and it needs an extra day, then the new RC could be delayed by a day.
• Circa Dec 2019, one of the ESR periods was extended by a month to improve alignment with common downstream fundraising calendars.