Skip to content

docs(admin): rewrite maintenance and release schedule chapter #15411

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
joshtrichards wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

docs(admin): rewrite maintenance and release schedule chapter #15411

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
225 changes: 148 additions & 77 deletions admin_manual/release_schedule.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,136 +2,207 @@
Maintenance and release schedule
================================

Overview
--------

Nextcloud releases multiple major versions *throughout* the year, but maintains support for *each* major version for one full year each through "lighter" maintenance updates (and regularly `backporting <https://en.wikipedia.org/wiki/Backporting>`_ applicable security and bug fixes). This permits a high velocity development cadence, while still giving administrators flexibility when planning deployments, upgrades, and maintenance activities.

A detailed `schedule for upcoming major and maintenance releases <https://github.com/nextcloud/server/wiki/Maintenance-and-Release-Schedule>`_ (as well as end-of-life projections) is regularly updated to facilitate planning deployment, testing, and upgrade planning.
.. admonition:: TL;DR

Whether you want the latest features and optimizations, want to help with testing, or just want to wait until everything is perfectly ready to go, you've got options with regards to which version of Nextcloud Server to initially deploy as well as how frequently to do major upgrades.
* Versioning scheme: ``MAJOR.MINOR.PATCH``
* Latest major release = leading-edge supported release with the newest
features and stable API additions
* Oldest supported major release = most mature supported release still
receiving security and critical bug fixes
* Release cadence and lifecycle:

.. danger:: We always recommend installing the latest **maintenance** releases as soon as possible, regardless of which major version of Nextcloud Server you use. And we also always highly recommend upgrading from **end-of-life** releases as soon as possible.

.. tip:: Extended maintenance and additional support is available through `subscriptions options for enterprise support <https://nextcloud.com/enterprise/>`_ offered by Nextcloud developers through `Nextcloud GmbH <https://nextcloud.com>`_.

Release types
-------------
- Major releases: released approximately every four months; supported
through maintenance releases for twelve months after initial release
- Maintenance releases: released approximately monthly for all supported
major versions; limited to critical bug fixes and security fixes

Nextcloud has two types of releases in the default release channel:
Overview
--------

1. Major releases
2. Maintenance releases
Nextcloud Server ``stable`` releases use a standard ``MAJOR.MINOR.PATCH``
versioning scheme. A release identified by the ``PATCH`` component is also
called a **maintenance release**.

**Major** releases of Nextcloud Server (e.g. ``28.X.X``) introduce new features and functionality.
``stable`` releases are point-in-time snapshots published by the maintainers.
They provide transition points for new features, architectural changes, major
dependency updates, API deprecations, and substantial technical debt reduction.
They also provide a consistent core user interface for end users and their
technical supporters, as well as a stable API surface for app developers.

Every major release is, in turn, supported for *one year* via periodic **maintenance** releases (e.g. ``X.X.4``), which correct critical bugs and security vulnerabilities.
Multiple ``stable`` major releases are supported at the same time. The
following sections describe the two ends of that support range.

Major releases
~~~~~~~~~~~~~~
The latest supported major version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Major releases usually introduce new features and often also include changes "under the hood". These changes may be extensive.
The **latest supported major version** is the leading-edge release deemed
generally ready for responsible production use by the core maintainers.

A specific major release is indicated by the first part of the version string. For example, Nextcloud Server ``28.0.4`` is major release ``28``. And ``27.1.7`` is major release ``27``.
It provides the newest features, refinements, and optimizations while
introducing the latest stable API surfaces and capabilities for app developers.
It is likely to receive additional polishing for edge cases based on community
feedback during its early maintenance releases.

.. tip:: The highest numbered major release offers the latest features. While the lowest numbered major release offers the most time in the field.
The oldest supported major version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note:: You may need to meet new system requirements before the Updater will offer you a new major version. Even if offered, there may be other changes required that the Updater cannot check for fully. We try to highlight these, in each new edition of the Admin Manual, in the Critical changes section of the *Release notes* chapter.
The **oldest supported major version** is the most mature and refined
option still actively receiving regular security and bug fixes. It has had
the longest period of production use and maintenance. It may have broader app
compatibility, depending on the apps you use, and typically broader community
support.

.. warning:: Apps generally define their compatibility based on the major version(s) of Nextcloud Server they support. Consider the compatibility of your favorite and most critical apps, with a prospective major version of Nextcloud Server, before choosing which major version to deploy or deciding when to upgrade to a newly available major version. Also, since many apps are community provided and maintained by volunteers, you may want to offer to test the app against a new major version of Nextcloud (or to adapt it, if you're in a position to do so) in order to encourage a faster (or higher quality) release.
Choosing what version to install
--------------------------------

Maintenance releases
~~~~~~~~~~~~~~~~~~~~
For upcoming Server release dates and the latest end-of-life projections,
see the `Maintenance and Release Schedule
<https://github.com/nextcloud/server/wiki/Maintenance-and-Release-Schedule>`_.

Maintenance releases deliberately **do not** introduce new features or breaking changes. This is meant to reduce the risks and impact associated with deploying updates so that critical bugs or security vulnerabilities can be rapidly and routinely addressed.
When choosing a version for a new installation, select any supported major
version according to your needs. Choose the latest supported version for the
newest features, or the oldest supported version for the greatest maturity.

Maintenance releases are published (generally simultaneously) for all stable major releases that have not reached end-of-life status.
.. tip::
Extended maintenance and additional support are available through
`Nextcloud Enterprise services <https://nextcloud.com/enterprise/>`_,
offered by Nextcloud GmbH, which employs many of the developers and core
maintainers who work on Nextcloud.

These releases should not have app compatibility concerns or introduce changes requiring retraining end users.
Release types
-------------

A specific maintenance release is indicated by the last part of the version number. For example, ``28.0.4`` is the *fourth* maintenance release for major version ``28`` of Nextcloud Server. It offers fixes for any critical bugs and security vulnerabilities addressed since the last maintenance release (``28.0.3`` in this example).
Nextcloud has two types of releases in the default ``stable`` release
channel:

.. note:: All critical bug fixes, including security related ones, are `backported <https://en.wikipedia.org/wiki/Backporting>`_ to **all** maintained major releases.
* **Major releases** introduce new features and functionality.
* **Maintenance releases** provide targeted fixes for supported major
versions.

Release schedule
----------------
Major releases
~~~~~~~~~~~~~~

New **major** releases of Nextcloud Server are published approximately every sixteen weeks.
A major release is identified by the first part of the version number. For
example, ``28.0.4`` belongs to major version ``28``.

New **maintenance** releases are published approximately every four weeks.
Major releases can introduce new features, behavioural changes, and changes to
system requirements. Apps may also need to be updated to support a new major
version.

Length of support ("maintenance")
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tip::
Before upgrading, review the *Critical changes* section
of the :doc:`release notes <release_notes>` and verify that your apps support
the target major version.

Our release schedule means that several major releases (e.g. 26.X.X, 27.X.X, 28.X.X) are supported simultaneously. Whenever a critical bug or vulnerability is addressed, if it impacts more than one major release, it is **backported** to all applicable major releases and published in the next maintenance release (e.g. ``28.0.3`` -> ``28.0.4``). Any major release that has not reached end-of-life status receives these maintenance updates.
**New major releases** are generally published **every four months**. The
actual schedule is subject to change.

This overlapping schedule and predictable cadence permits rapid development while giving administrators visibility, access to critical bug fixes, and flexibility as to how aggressively to upgrade to new majors.
Each major release is supported through maintenance releases for twelve months
from its initial release. Enterprise support arrangements with Nextcloud GmbH
may provide longer support periods.

.. note:: Since every major release is supported for one year from initial release, the minimum you need to do to stay up-to-date is to install maintenance releases as they're published and upgrade to the next higher up major release when the one you're currently on reaches end-of-life status. Since maintenance releases only patch your Server with the latest bug and security vulnerability fixes - and do **not** introduce other significant changes - the risk of upgrading to a new maintenance release is far less than upgrading to a new major release.
Maintenance releases
~~~~~~~~~~~~~~~~~~~~

End-of-life
~~~~~~~~~~~
A maintenance release is identified by the ``PATCH`` part of the version
number. For example, ``28.0.4`` is the fourth maintenance release for major
version ``28``.

End-of-life status means that support/maintenance ends. Maintenance releases cease for a major version on the one year anniversary of initial release. The major version then moves into end-of-life status and will not receive any further bug fixes or corrections for security vulnerabilities.
Maintenance releases do not introduce new features or breaking changes. Their
content is limited to targeted or backported critical changes, including
critical bug fixes and security fixes.

.. note:: Support for major releases may be extended through `subscription services for enterprises <https://nextcloud.com/enterprise/>`_ offered by Nextcloud developers via `Nextcloud GmbH <https://nextcloud.com>`_.
**Maintenance releases** are published approximately **once per month** for
each supported major version. Critical fixes that affect more than one
supported major release are backported to all affected versions.

The end-of-life dates for all major releases are `published <https://github.com/nextcloud/server/wiki/Maintenance-and-Release-Schedule>`_ ahead of time to ease planning.
.. danger::
Always install the latest maintenance release available for your chosen
major version as soon as possible.

.. note:: As long as a major release is still listed on the `maintenance schedule <https://github.com/nextcloud/server/wiki/Maintenance-and-Release-Schedule>`_ as being *Currently Maintained*, you can expect to receive all relevant fixes for critical bugs or security vulnerabilities (even those made available for newer major releases, if they are relevant to a still supported earlier major).
End of life
-----------

Installation version
---------------------
A major version reaches its end of life twelve months after its initial
release. After that anniversary, community maintenance releases, including
security fixes, cease.

Since multiple major releases are published throughout the year and each is supported for a year with any relevant bug and security fixes, you have discretion as to which which major to deploy initially as well as when to upgrade to a new major.
.. tip::
Try to complete your upgrade to the next supported major version before your
current major version reaches end of life. With approximately three major
releases every twelve months, you generally have eight to twelve months to
plan the next major version upgrade, depending on when you upgrade.

.. note:: If you're planning to deploy Nextcloud in an enterprise setting and your usage will be mission-critical, the developers can help you choose, via an `Enterprise services arrangement <https://nextcloud.com/enterprise/>`_, the major version most suitable for your particular use case as well as help make sure it's deployed optimally while addressing any critical problems that arise with you one-on-one.
The current maintenance status and planned end-of-life dates are published in
the `Maintenance and Release Schedule
<https://github.com/nextcloud/server/wiki/Maintenance-and-Release-Schedule>`_.

Release channels
----------------

By default all Nextcloud installations utilize the ``stable`` release channel. This channel delivers the latest features that are ready for most users at minimal risk.

.. note:: Nextcloud does staged roll-outs of new releases to further reduce the risk of widespread updates. New releases, particularly major releases, are usually only made available to a small percentage of systems initially. After a week (or more) has passed with no reported widespread critical bugs, more systems will be offered the update. Sometimes major versions are limited to <100% of systems until after the first maintenance (bug fix) release has been published.

.. warning:: When using the ``stable`` channel it is possible you'll be *offered* a newer major version to upgrade to *even if* your existing major version has **not** reached end-of-life. It is up to you to decide whether to upgrade then or wait until a better time for deploying a major new release. On the other hand, new **maintenance** releases (within the major version you're already running) should be deployed as soon as possible to keep up-to-date with security and other critical bug fixes.
By default, Nextcloud uses the ``stable`` release channel. This channel
provides releases that are ready for most users. New releases are introduced
gradually through staged roll-outs.

.. danger:: Making sure you're running an actively maintained **major** release is critical. Once a major release reaches End of Life status it will not receive any further maintenance releases to correct critical bugs or vulnerabilities.

You can find the detailed schedule for all stable channel major releases and maintenance releases, including end-of-life dates, in our regularly updated `Maintenance and Release Schedule <https://github.com/nextcloud/server/wiki/Maintenance-and-Release-Schedule>`_.
The ``stable`` channel may offer a newer major version before your current
major version reaches end of life. You are not required to upgrade immediately,
but you must upgrade before your current major version becomes unsupported.

Major version upgrades
----------------------

Before upgrading from one one major release to another, we strongly recommend reviewing the *Critical changes* section of the **Release Notes** chapter to minimize the chance of introducing unexpected breaking changes in your environment.
Before upgrading between major versions:

.. warning:: Having good data backups (and a tested data restore approach!) is recommendeded in general, but definitely before performing an update - whether major or merely maintenance.
* Review the *Critical changes* section of the release notes.
* Check the compatibility of your apps.
* Verify that your system meets the target release's requirements.
* Create a backup and test that you can restore it.

Beta releases and Release candidates
------------------------------------
Downgrading is not officially supported between major, maintenance, or
pre-release versions.

Before a new final major release is published, typically at least four beta releases are published followed by two release candidates, with an interval of one week between each.
Bug reporting
-------------

Before a new final maintenance release is published, one release candidate is published approximately one week beforehand.
Before reporting a bug, make sure that you are running a supported major
version and the latest maintenance release for that version.

Anticipated dates for each release can be found on `detailed schedule <https://github.com/nextcloud/server/wiki/Maintenance-and-Release-Schedule>`_.
Other release schedules
-----------------------

.. tip:: To update sooner to a new major version or beta version, you may at your discretion adjust your instance to use the ``beta`` channel. Around big releases the ``beta`` channel also delivers the newest major version earlier regardless of staging parameters.
The following components are related to Nextcloud Server but do not necessarily
follow its versioning scheme or release schedule.

Everyone in the community benefits considerably from the generous testing and feedback of those that choose to evaluate beta releases or release candidates in either their test environments or, for the bold, under real-world conditions.
Pre-releases
~~~~~~~~~~~~

If you are in a position to evaluate a pre-final release, the developers and the entire community thank you!
Community members can help with quality assurance and real-world testing by
deploying beta releases and release candidates. Use pre-releases in test
environments and be prepared to identify and report problems.

.. tip:: We suggest focusing your testing efforts on verifying the functionality and features you rely on every day (to make sure these operate as expected). Then, if you are so inclined, to consider evaluating any new functionality that interests you. Please discuss problems that arise at the `Help Forum <https://help.nextcloud.com>`_ and report suspected bugs to `the GitHub repository <https://github.com/nextcloud/server/issues>`_.
For archive-based installations, you can select the ``beta`` release
channel to test upcoming releases.

Downgrading
-----------
App releases
~~~~~~~~~~~~

Downgrading is not supported officially between any major, maintenance, or pre-release version.
Nextcloud apps, including *Recommended* and *Featured* apps but excluding
shipped core apps, have their own versioning schemes and release schedules.

Bug reporting
-------------
Installers and deployment packages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The main artifacts for a given Nextcloud Server release are the ``.tar.gz`` and
``.zip`` archives generated and published by the core project maintainers.
They are versioned as described above.

Most other Nextcloud installation packages, such as AIO and Snap, are
maintained as sub-projects or community projects. They each have their own
versioning schemes and release schedules, which may not coincide with those of
the core project.

Before reporting bugs, please make sure you're running a still supported major release *and* the latest maintenance release for it.
Official clients
~~~~~~~~~~~~~~~~

.. tip:: Nextcloud GmbH - which employs many of the core developers - offers `Nextcloud Enterprise services <https://nextcloud.com/enterprise/>`_ providing direct access to Nextcloud engineering expertise where usage is mission-critical. Among other things, they can help you choose the major version most appropriate to your use case (and make sure it's deployed optimally).
All official clients (mobile, desktop) have their own versioning schemes and
release schedules.
Loading