Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History

Table of Contents

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 stable mini releases while working on more significant releases in parallel.

This methodology should strike the right balance between a high-quality process and making 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.

Definitions

Core

The trunk of the framework repository, from which minor and major release candidate branches are generated, is known as the framework core.

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

Incubator

The incubator directory is where new development matures to a state acceptable for the framework core, from which minor and major release candidate branches 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.

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.

Mini Release

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

Minor Release

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

Major Release

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

Product Releases

Mini Release

Goal

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

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 many 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.

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, to facilitate the timely generation of an emergency release should the need arise.

Minor Release

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.

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.

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.

Major Release

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.

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.

Release Cycle

Major releases will usually be driven by a combination of features and date. They 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.

Development Tasks

Performing a Checkout

Before starting any development work on the Zend Framework, whether on source code, documentation, or unit tests, you will need a Subversion working copy of the sources. In order to obtain a working copy of the Zend Framework, or some portion thereof, you may use the svn checkout command, as in the following example, which checks out the entire framework trunk:

It is recommended that developers checkout a working copy of each of the trunk (core) and any active release branches. The above command illustrates how to checkout the framework trunk, and the following command checks out the release-1.0 branch into a sibling directory:

Switching a Working Copy between Branches

Though developers will likely find it most convenient to have separate working copies of the trunk (core) and a release branch, it is possible to switch a single working copy between branches. You can switch all or a portion of your working copy between two branches by using the svn switch command, as in the following example, where a working copy of the trunk is switched to a hypothetical purpose branch containing experimental Zend_View changes:

To switch back to the trunk, simply run the command again with the URL of the trunk:

Merging Changes

Merging changes from one branch to another is made quite simple in Subversion, since it is merely a copying of differences between revisions. Since, at the time of this writing, the framework Subversion repository does not natively support merge tracking, it is very important to note the applicable revision range for all merge operations in the commit message, as in the following example:

By indicating the merged revisions in the commit message, it is simple to note which revisions have been merged and which have not. The svn merge command may be formulated in one of three ways; please see the SVN documentation for more information.

Backward Incompatible Changes

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.

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.

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.

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 or major release, whichever occurs first. 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.

As an example, assume that you have just committed to the trunk a code fix for a small bug in a framework component, along with unit tests that confirm the desired resulting behaviors. Zend Framework 1.0.0 has just been released, and the next planned release is a 1.0.1 mini release. The next minor release is planned to be 1.1.0. The associated JIRA issue that tracks the bug should be marked as fixed for 1.1.0. Once the changes are reviewed, you should merge the changes to the 1.0 release branch, so that they may also be included in the 1.0.1 release. Once you have committed the merge, mark the JIRA issue as fixed for not only 1.1.0 but also 1.0.1.

Repository Structure Explained

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

Unable to render embedded object: File (ZF_SVN.png) not found.

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.

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.

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.

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.

Example Scenarios

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.

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.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.