Releasing Neos and Flow
This page provides an overview of how we approach releases. Neos and Flow have the same release lifecycle and release process.
For users of Neos it explains what to expect in a release and when when release is done.
For release managers it helps to understand their role in this process.
What's in a Release?
While this may be an interesting question to some, it isn't to us. In some cases we might plan a certain feature to be done for a specific release, but in general we just work on features and merge them into the master branch when they are done.
From this branch the next minor release is done as scheduled. So whenever a feature is merged in master, it is known when it will be released.
Breaking changes are usually held back (maybe in a separate branch or even a developer's fork) until it is known the next release done off of master will be a major release. Another option is the use of a branch to officially collect changes for the next major release earlier.
Neos releases follow Semantic Versioning, meaning in a nutshell that given a version number MAJOR.MINOR.PATCH, increments to the:
- MAJOR version indicate incompatible changes to the public API,
- MINOR version indicate added functionality in a backwards-compatible manner, and
- PATCH version indicate backwards-compatible bug fixes.
See semver.org for the full details on this.
It is notable that a major release is not always defined by great new features. Features are introduced in minor releases as well. But a major release will come with breaking changes (and usually some new features made possible by them).
Definition of Incompatible Changes
For semantic versioning to work, one needs to know what the public API of a system is. The public API of Neos and Flow is made up of the following components:
- PHP API as documented
- Validator settings, ViewHelpers, TypoScript objects, Eel helpers, FlowQuery operations
- Configuration provided by our packages (YAML files in the various packages)
- Settings: no removals / renames are allowed!
- Caches: adding caches / changing defaults must be documented!
- Policy: the syntax, predefined roles
- Objects: syntax (possible changes limited by public API)
- Routes: syntax (in general there should be few interaction with third-party packages)
- NodeTypes: predefined node types
- Settings: no removals / renames are allowed!
- Database schema: migrations that do irreversibly change data or lead to downtime
- Public default output (e.g. Neos markup in frontend, like the CSS classes)
- Minimum requirements (PHP or Browser versions)
Every change to the above which requires an action by the user, integrator or developer which can't be easily executed as an automated task during deployment is a breaking change and requires a major version to be released.
According to that definition, code migrations are breaking, but database schema upgrades or node migrations (if they can really be executed safely during a deployment) are okay.
Even the cases were the needed adjustments can be automated will be clearly documented so the user can assess the impact of such a change.
When following Semantic Versioning, there is no point in releasing one major version after another. That means we need to take an extra look on changes which break backwards-compatibility. A release schedule helps to plan ahead - if we know when the next major version is being scheduled, we can either postpone backwards incompatible changes to a later version or maybe find a creative way to make the change compatible.
- Three minor releases per year, with patch level releases as needed in between
- Major releases happen yearly, assuming there will be breaking changes
- Each release receives bug fixes for 1 year and security fixes for 1 additional year (2 in total)
- Each Long Term Support (LTS) version receives bug fixes for 2 years and security fixes for 1 additional year (3 in total)
This results in a simple and predictable scheme. In the (unlikely) event of no breaking changes being present, no major version is released, minor versions are released instead. In such a case a minor release will be declared as LTS, making sure the flow of LTS releases stays intact.
The Release Cycle
A Release Manager is responsible for a release branch that includes a specific new release and all of its bugfix releases (i.e. The Release Manager for 2.0 is responsible for 2.0.1, but not 2.1). The Release Manager is responsible, throughout the maintenance lifetime of their specific release branch, for the following things:
- Schedule and coordinate contributions for a specific release branch and all of its bugfix releases.
- Prevent feature creep within the release branch by having a vision of what features can or should be included in the release.
- The release manager has the final say on which changes can be included in the release.
- Make sure that any major features are included in release notes before the feature is merged into the release.
- Collaborate with the community contact and public relations manager to:
- communicate the timeline and release branch vision,
- write and distribute release announcements, and
- other release specific communication.
- Be available to answer questions about whether or not to include a change in the release branch.
- Make sure releases happen, including the release branch's new release and all bugfix releases (See "The Release Process" below).
- Neos 2.2 release manager:
- Neos 2.1 was coordinated by:
the Minions team
- Neos 2.0 release managers:
Aske Ertmann and Christian Müller
- Neos 1.2 release manager:
older versions not maintained any more:
- Neos 1.1 release manager:
- Neos 1.0 release manager:
- Flow 3.0 release manager:
Breaking the Rules
This policy will be followed on a best-effort basis. In extreme cases it may not be possible to support a release for the planned lifetime; for example if a serious bug is found that cannot be resolved in a given major version without significant risk to the stability of the code or loss of compatibility. In such cases, early retirement of a version may be required.