Zend Framework Version Lifecycle

h1. Table of Contents

{toc-zone:location=top|type=list|style=none|outline=true|indent=20px|printable=true}

h1. Document Overview

The goal of this document is to clearly articulate the development lifecycle methodology for Zend Framework. There are many challenges in managing such a project, mainly due to the large number of contributors, the increasing amount of translated documentation, and the need to release both stable mini releases while working on more significant releases in parallel.

The goals in writing this methodology are to find the right balance between a high-quality process and to make it reasonably easy to become a contributor. The suggested practices in this document aim to meet these goals, but they will only succeed with the help of peer review and support.

Over time we will continue to evolve and update these practices based on real-world application.


h1. Definitions

h2. Core

The trunk of the framework repository, from which release candidates are generated, is known as the framework core.

Before code is permitted to enter the framework core, passing unit tests and documentation are required.

h2. Incubator

The incubator directory is where new development matures to a state acceptable for the framework core, from which release candidates are produced. It should be used to develop first-time components after their respective proposals have been accepted. It is also used to develop new component adapters (e.g., for Zend_Auth, Zend_Cache, Zend_Db) and to implement large units of work such as major architectural changes or experimental improvements. Once such new developments reach the project's baseline for quality (code, unit tests & documentation) they will be promoted and maintained in the trunk directory.

If multiple parallel development efforts should occur for a given component, then additional branches of the main development line may be provided for accommodating the work. In any case, software configuration management solutions, such as Subversion, are no substitution for effective communication among developers.

h2. Release Master

The release master is a member of the Zend Framework team who will lead the release process for a given version. The release master is responsible for making a release converge by making sure the various contributing parties have satisfactorily completed their deliverables, ensuring there are no show stopper bugs and ultimately to recommend a release-ready product.

h2. Mini Release

Mini releases increment the third digit of the version number, i.e. 1.0.x.

h2. Minor Release

Minor releases increment the second digit of the version number, i.e. 1.x.0

h2. Major Release

Major releases increment the first digit of the version number, i.e. x.0.0


h1. Product Releases

h2. Mini Release

h3. Goal

The goal of a mini release is to deliver important bug fixes to the user-base.

h3. Backward Compatibility

Backward compatibility should strictly be adhered to in mini releases unless a high-impact critical bug such as a security bug demands otherwise. In some cases adding minor feature enhancements is acceptable if they are self-contained and the release master decides these changes are at low risk of impacting existing functionality.

h3. Release Cycle

Mini releases will not be date driven. They will be driven at the discretion of the release master when he believes enough fixes have accumulated to warrant a release. We believe such releases will be done initially every 4-8 weeks. For high-impact critical bugs the release master may decide to release sooner. The mini release branch should always be stable and in a releasable state.

h2. Minor Release

h3. Goal

The goal of a minor release is to deliver additional feature enhancements in both new and existing components including a variety of bug fixes.

h3. Backward Compatibility

Backward compatibility should be adhered to in minor releases. Significant enhancements to existing components may pose a risk to backward compatibility; therefore the goal will be to try and add sufficient unit tests to cover the affected areas and expected behaviors to minimize the risks due to the source code changes. In certain cases when there's a high-impact bug or it is not feasible to keep backward compatibility, the release master may recommend otherwise. In cases of exceptions the release master will make a calculated risk assessment depending on the scope of the change and area of change. For example, changes in Web Services APIs will be considered much less critical than changes in the MVC or Database components. In fact, Web Services APIs is one area where we do believe there will be more frequent changes in minor-releases as the vendors are constantly tweaking their services.

h3. Release Cycle

Minor releases will usually be date driven. There will be a "release train" and new developments that want to be part of that will have to be ready in time. As quality is our main goal, we will not ship work which is not complete by that time. We believe such releases will be done initially approx. 3 times a year.

h2. Major Release

h3. Goal

The goal of a major release is to deliver significant enhancements to the Zend Framework. Such enhancements could include major new features with far reaching benefits and/or major architectural changes.

h3. Backward Compatibility

Typically the goal of a major release also includes making significant architectural improvements which often may somewhat break backward compatibility. While backward compatibility breaks in major versions are acceptable, the goal will still remain for as few breaks as possible to happen.

h3. Release Cycle

Major releases will usually be driven by a combination of features and date. It would include the minimum amount of features in order for the major release to be considered appropriate but then may very well be driven by a release train in order to bring the release to completion. We expect major releases to come out approx. every 18 months.

API changes that are by necessity incompatible with previously released versions of the framework require special attention. Such changes must be assessed for risk and approved on a case-by-case basis before such changes are made.

An approved set of backward-incompatible changes should be accompanied by an upgrade script, which can take an application and resolve backward compatibility breaks automatically by substituting the syntax with the new version. If this isn't possible, then the script should try and detect code which needs manual repairing. In any case, the release notes (see {{UPDATING.txt}}) should accurately reflect the backward incompatible changes and their remedies. Where significant efforts must be made by framework users to accommodate the changes, a migration process may be required for the framework documentation in order to accept the backward incompatible changes.

h2. Commits to Trunk

Small, self-contained bug fixes and enhancements that are less than a day of work can be made to the trunk (a.k.a. "core"). Unit tests for the changes need to pass before check-in. Larger changes should be made in the incubator or in a new purpose branch, if the incubator is already occupied. This facilitates parallel development efforts by enabling daily check-ins of incomplete code for backup and review purposes, without compromising the integrity of the framework core.

h2. Merging Work into Core

All the unit tests have to pass before a committer considers merging branched work into the trunk. In addition, there should be unit tests that test the areas of code which have been affected. Merges into core should be coordinated with the release master.

h2. JIRA Workflow

When a committer fixes a bug, it should be marked as fixed for all versions of the branches to which the fixes have been applied. For example, if a fix is committed to the trunk, then it will be included with the next minor release. If the same fix is then merged to one or more release branches, then the JIRA issue should also be marked as fixed for the next mini releases associated with those branches.


h1. Repository Structure Explained

The following diagram illustrates the planned structure of the ZF Subversion (SVN) repository:

!ZF_SVN.png!

New development typically occurs in the incubator or a purpose branch if the incubator is already occupied. Once progress has reached a mature enough status (working code, passing tests, and good documentation), it is migrated to core (the trunk).

In anticipation of an impending minor or major release, the trunk is branched to a release branch (e.g., release-1.1) on or about the time of code freeze. After the release branch has been created, changes to this branch may only occur in coordination with the release master. Critical fixes may be allowed, but in general, the release branch must remain as stable as possible for testing and quality assurance leading up to the actual release.

When final testing is complete, and the release branch is deemed ready for release, a tag is created from the release branch.

This process isolates the release candidate and allows for continuing parallel developments in the trunk, even during the code freeze for a release.

Tags are considered read-only; no changes whatsoever are to occur within a tag.

h2. Source code

Zend Framework will aim to always have two active branches at any given time. One active branch is to maintain the last stable version (e.g., 1.0.0, 1.1.0). From this branch mini releases (e.g., 1.0.1, 1.1.1) are made. This is also known as the maintenance branch. The other active branch is for developing the next minor or major release, and it is the trunk (a.k.a. core), or development branch. All commits should first be made to trunk (after having completed the work in the incubator or a purpose branch, if necessary), and then all complete and tested fixes that are deemed as not breaking backward compatibility should be merged to the maintenance branch by the author. Before the merge, the author should find a Zend liaison or community member to peer-review the changes in order to decrease the chances of problems finding their way into the stable stream. This should happen _immediately_ after the bug fix has been completed and fully committed to trunk. The release master and the community should play an active role in reminding contributors to do so. Committers who repeatedly fail to merge their bug fixes to the maintenance branch may risk their commit access to be suspended for a period of time.

h2. Unit tests

Unit tests will be treated similarly to source code contributions, although there will be more flexibility in making larger changes to the maintenance branch (at the discretion of the release master). In general, adding unit tests that pass and cover more of the framework source code and expected behaviors are most welcome additions that contribute to the quality and stability of the framework.

h2. Documentation

Due to the difficulties of merging documentation and in maintaining translations for two branches of documentation, documentation authoring will only happen in the trunk. There should be _no_ documentation fixes or enhancements in the maintenance branch. New features in the development branch should be clearly marked with the version of ZF from which they appear. On the same note, deprecated features should be marked as deprecated with the version of ZF from which they've been deprecated. An exception is a new major version where the Zend Framework team might decide to branch the documentation depending on the significance of the changes.

h2. Example Scenarios

h3. Minor Change

Let's assume that you need to commit a small, backward-compatible change to a component. You expect the change to take about an hour to complete. This development should be committed to the trunk along with passing unit tests that confirm the intended behavior of the change. Documentation may need to be updated if, for example, the change introduces additional optional method parameters.

Once the work is complete, unit tests pass, and the documentation builds successfully without errors, commit the work to the trunk. Ask other community members and/or Zend to review the changes. After sufficient review evidences the correctness and stability of the change, immediately commit the code changes and unit tests to the maintenance branch. Documentation changes should not be propagated to the maintenance branch.

h3. Major Change

Consider now that you need to make a major change to a component, such as a new feature. For this example, let's assume that the changes will be backward-compatible. You expect the development to take about a week to complete, including unit tests and documentation (where applicable).

In this case, the incubator (or a purpose branch, if necessary) should be utilized to accommodate your daily commits. These commits do not interfere with the stability of the trunk and can be made as often as possible (at least once per day, hopefully more). It is the responsibility of the developers to merge others' changes from the trunk, in order to ensure that their development stays in sync. Once the changes are complete with passing unit tests and documentation that successfully builds without errors, ask other community members and/or Zend to review the work. After sufficient review, the changes may be merged onto the trunk.

{toc-zone}