compared with
Current by Thomas Weidner
on May 04, 2010 13:04.

(show comment)
Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (160)

View Page History
h1. Table of Contents
<h1>Table of Contents</h1>

{toc-zone:location=top|type=list|style=none|outline=true|indent=20px|printable=true}
<ac:macro ac:name="toc-zone"><ac:parameter ac:name="location">top</ac:parameter><ac:parameter ac:name="type">list</ac:parameter><ac:parameter ac:name="style">none</ac:parameter><ac:parameter ac:name="outline">true</ac:parameter><ac:parameter ac:name="indent">20px</ac:parameter><ac:parameter ac:name="printable">true</ac:parameter><ac:rich-text-body>

h1. Document Overview
<h1>Document Overview</h1>

<p>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.</p>

<p>Thivn 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.</p>

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


h1. Definitions
<h1>Definitions</h1>

h2. Core
<h2>Core</h2>

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

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

h2. Incubator
<h2>Incubator</h2>

<p>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 & &amp; documentation) they will be promoted and maintained in the trunk directory.</p>

<p>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.</p>

h2. Release Master
<h2>Release Master</h2>

<p>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.</p>

h2. Mini Release
<h2>Mini Release</h2>

<p>Mini releases increment the third digit of the version number, i.e. 1.0.x.</p>

h2. Minor Release
<h2>Minor Release</h2>

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

h2. Major Release
<h2>Major Release</h2>

<p>Major releases increment the first digit of the version number, i.e. x.0.0</p>


h1. Product Releases
<h1>Product Releases</h1>

h2. Mini Release
<h2>Mini Release</h2>

h3. Goal
<h3>Goal</h3>

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

h3. Backward Compatibility
<h3>Backward Compatibility</h3>

<p>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.</p>

h3. Release Cycle
<h3>Release Cycle</h3>

<p>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.</p>

h2. Minor Release
<h2>Minor Release</h2>

h3. Goal
<h3>Goal</h3>

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

h3. Backward Compatibility
<h3>Backward Compatibility</h3>

<p>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.</p>

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.
<h3>Release Cycle</h3>

h2. Major Release

h3. Goal
<p>Minor releases will usually be date driven. There will be a &quot;release train&quot; 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.</p>

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.
<h2>Major Release</h2>

h3. Backward Compatibility
<h3>Goal</h3>

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
<p>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.</p>

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.
<h3>Backward Compatibility</h3>

<p>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. </p>

h1. Development Tasks
<h3>Release Cycle</h3>

h2. Performing a Checkout
<p>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.</p>

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|http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.checkout.html]}} command, as in the following example, which checks out the entire framework trunk:

<h1>Development Tasks</h1>
{code}
<h2>Performing a Checkout</h2>

<p>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 <code><a href="http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.checkout.html">svn checkout</a></code> command, as in the following example, which checks out the entire framework trunk:</p>

<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ svn checkout http://framework.zend.com/svn/framework/trunk ZendFramework-trunk
{code}
]]></ac:plain-text-body></ac:macro>

<p>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:</p>

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ svn checkout http://framework.zend.com/svn/framework/branch/release-1.0 ZendFramework-release-1.0
{code}
]]></ac:plain-text-body></ac:macro>

h2. Switching a Working Copy between Branches
<h2>Switching a Working Copy between Branches</h2>

<p>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|http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.switch.html]}} <code><a href="http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.switch.html">svn switch</a></code> 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:</p>

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ svn switch http://framework.zend.com/svn/framework/branch/Zend_View .
{code}
]]></ac:plain-text-body></ac:macro>

<p>To switch back to the trunk, simply run the command again with the URL of the trunk:</p>

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ svn switch http://framework.zend.com/svn/framework/trunk .
{code}
]]></ac:plain-text-body></ac:macro>

h2. Merging Changes
<h2>Merging Changes</h2>

<p>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 <strong>note the applicable revision range for all merge operations in the commit message*, message</strong>, as in the following example:</p>

{code}
<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
$ svn merge -r 25:35 http://framework.zend.com/svn/framework/branch/Zend_View
...
$ svn commit -m 'Merge to trunk changes from the Zend_View branch r25 to r35'
{code}
]]></ac:plain-text-body></ac:macro>

<p>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|http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.merge.html]}} <code><a href="http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.merge.html">svn merge</a></code> command may be formulated in one of three ways; please see the SVN documentation for more information.</p>

h2. 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.
<h2>Backward Incompatible Changes</h2>

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.
<p>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.</p>

h2. Commits to Trunk
<p>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 <code>UPDATING.txt</code>) 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.</p>

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>Commits to Trunk</h2>

h2. Merging Work into Core
<p>Small, self-contained bug fixes and enhancements that are less than a day of work can be made to the trunk (a.k.a. &quot;core&quot;). 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.</p>

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>Merging Work into Core</h2>

h2. JIRA Workflow
<p>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.</p>

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.
<h2>JIRA Workflow</h2>

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.
<p>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.</p>

<p>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.</p>

h1. Repository Structure Explained

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).
<h1>Repository Structure Explained</h1>

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.
<p>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).</p>

When final testing is complete, and the release branch is deemed ready for release, a tag is created from the release branch.
<p>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.</p>

This process isolates the release candidate and allows for continuing parallel developments in the trunk, even during the code freeze for a release.
<p>When final testing is complete, and the release branch is deemed ready for release, a tag is created from the release branch.</p>

Tags are considered read-only; no changes whatsoever are to occur within a tag.
<p>This process isolates the release candidate and allows for continuing parallel developments in the trunk, even during the code freeze for a release.</p>

h2. Source code
<p>Tags are considered read-only; no changes whatsoever are to occur within a tag.</p>

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. 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>Source code</h2>

h2. Unit tests
<p>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. This should happen <em>immediately</em> 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.</p>

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>Unit tests</h2>

h2. Documentation
<p>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.</p>

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>Documentation</h2>

h2. Example Scenarios
<p>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 <em>no</em> 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.</p>

h3. Minor Change
<h2>Example Scenarios</h2>

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.
<h3>Minor Change</h3>

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.
<p>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.</p>

h3. Major Change
<p>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.</p>

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).
<h3>Major Change</h3>

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.
<p>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).</p>

<p>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.</p>
{toc-zone} </ac:rich-text-body></ac:macro>