compared with
Current by Martin de Keijzer
on Feb 14, 2011 12:07.

Key
This line was removed.
This word was removed. This word was added.
This line was added.

Changes (109)

View Page History
h1. Contributing to the Zend Framework -- Getting Started
<h1>Contributing to Zend Framework</h1>

{toc:type=list|style=none|outline=true|indent=20px|printable=true|minLevel=2}
<ac:macro ac:name="toc"><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:parameter ac:name="minLevel">2</ac:parameter></ac:macro>

h2. Read the Zend Framework License
<h2>Read the license</h2>

The license is BSD based and can be found at http://framework.zend.com/license.
<p>Zend Framework is licensed under the New BSD License. It can be found <a href="http://framework.zend.com/license/">here</a>.</p>

h2. Sign a Contributor License Agreement
<h2>Sign the Contributor License Agreement (CLA)</h2>

To contribute source code or documentation into the framework at any level (from a few lines, through a patch, to a full set of classes), you must first sign the [Contributor License Agreement|http://framework.zend.com/wiki/display/ZFPROP/Contributor+License+Agreement]. This will also give you access to become a developer in the issue tracking system and the developer's wiki.
<p>To contribute source code or documentation at any level (from a few lines, to a patch, to a proposal, to an entirely new component), you must first sign the <a href="http://framework.zend.com/wiki/display/ZFPROP/Contributor+License+Agreement">Contributor License Agreement</a>. This will also give you access as a developer in the issue tracking system and the wiki.</p>

CLA signers who also establish a wiki account on this website, will be listed on our [Project Teams|$4118] page. thus, others will know who to accept code contributions from, and who they can work with in drafting proposals.
<p><ac:macro ac:name="anchor"><ac:default-parameter>mailing-lists</ac:default-parameter></ac:macro></p>
<h2>Subscribe to the appropriate mailing lists</h2>

h2. Subscribe to the appropriate mailing lists
<ac:macro ac:name="include"><ac:default-parameter>Mailing Lists</ac:default-parameter></ac:macro>

Please join us by subscribing to the mail lists that interest you, using the email account you wish to send messages from.
<h3>RSS</h3>
<p><ac:link><ri:page ri:content-title="RSS Feeds and Notifications" /><ac:link-body>RSS feeds and custom event notifications</ac:link-body></ac:link> are also available from our website. </p>

h3. RSS
[RSS feeds and custom event notifications|Zend Framework RSS Feeds and Notifications] are also available from our systems.
<h2>Contribute to the wiki</h2>

h3. ZF Mail Lists
<table><tbody>
<tr>
<th><p>Topic</p></th>
<th><p>URL</p></th>
</tr>
<tr>
<td><p>ZF1 Development</p></td>
<td><p><a href="http://framework.zend.com/wiki/display/ZFDEV">http://framework.zend.com/wiki/display/ZFDEV</a></p></td>
</tr>
<tr>
<td><p>ZF2 Development</p></td>
<td><p> <a href="http://framework.zend.com/wiki/display/ZFDEV2">http://framework.zend.com/wiki/display/ZFDEV2</a></p></td>
</tr>
<tr>
<td><p>Proposals</p></td>
<td><p><a href="http://framework.zend.com/wiki/display/ZFPROP">http://framework.zend.com/wiki/display/ZFPROP</a></p></td>
</tr>
<tr>
<td><p>End-user wiki</p></td>
<td><p><a href="http://framework.zend.com/wiki/display/ZFUSER">http://framework.zend.com/wiki/display/ZFUSER</a></p></td>
</tr>
</tbody></table>

[Searchable ZF Mail Lists|http://www.nabble.com/Zend-Framework-Community-f16154.html]
We would like to make searchable achives available using ZF and Zend_Search_Lucene, but Nabble's archive works now.

||List||Unsubscribe||Subscription Address||Archives||
|[Announcements|http://framework.zend.com/]|[Unsubscribe|mailto:fw-announce-unsubscribe@lists.zend.com]|[fw-announce-subscribe@lists.zend.com|mailto:fw-announce-subscribe@lists.zend.com]| |
|[Auth|http://framework.zend.com/wiki/x/qBM]|[Unsubscribe|mailto:fw-auth-unsubscribe@lists.zend.com]|[fw-auth-subscribe@lists.zend.com|mailto:fw-auth-subscribe@lists.zend.com]| |
|[Core|http://framework.zend.com/wiki/x/QxM]|[Unsubscribe|mailto:fw-core-unsubscribe@lists.zend.com]|[fw-core-subscribe@lists.zend.com|mailto:fw-core-subscribe@lists.zend.com]| |
|[DB|http://framework.zend.com/wiki/x/0xM]|[Unsubscribe|mailto:fw-db-unsubscribe@lists.zend.com]|[fw-db-subscribe@lists.zend.com|mailto:fw-db-subscribe@lists.zend.com]| |
|[Documentation|http://framework.zend.com/wiki/x/_ws]|[Unsubscribe|mailto:fw-docs-unsubscribe@lists.zend.com]|[fw-docs-subscribe@lists.zend.com|mailto:fw-docs-subscribe@lists.zend.com]| |
|[Gdata|http://framework.zend.com/wiki/x/9hw]|[Unsubscribe|mailto:fw-gdata-unsubscribe@lists.zend.com]|[fw-gdata-subscribe@lists.zend.com|mailto:fw-gdata-subscribe@lists.zend.com]|
| <h2>Report, work on, and resolve issues in the issue tracker</h2>
|[General|http://framework.zend.com/]|[Unsubscribe|mailto:fw-general-unsubscribe@lists.zend.com]|[fw-general-subscribe@lists.zend.com|mailto:fw-general-subscribe@lists.zend.com]|[http://framework.zend.com/wiki/spaces/viewmailarchive.action?key=ZFMLGEN] \\ [http://www.nabble.com/Zend-Framework-f15440.html]|
|[I18N/Locale|http://framework.zend.com/wiki/x/Lx]|[Unsubscribe|mailto:fw-i18n-unsubscribe@lists.zend.com]|[fw-i18n-subscribe@lists.zend.com|mailto:fw-i18n-subscribe@lists.zend.com]| |
|[MFS|http://framework.zend.com/wiki/x/mRI]|[Unsubscribe|mailto:fw-formats-unsubscribe@lists.zend.com]|[fw-formats-subscribe@lists.zend.com|mailto:fw-formats-subscribe@lists.zend.com]| |
|[MVC|http://framework.zend.com/wiki/x/mhI]|[Unsubscribe|mailto:fw-mvc-unsubscribe@lists.zend.com]|[fw-mvc-subscribe@lists.zend.com|mailto:fw-mvc-subscribe@lists.zend.com]| |
|[Server|http://framework.zend.com/wiki/x/Fx]|[Unsubscribe|mailto:fw-server-unsubscribe@lists.zend.com]|[fw-server-subscribe@lists.zend.com|mailto:fw-server-subscribe@lists.zend.com]| |
|[SVN commits|http://framework.zend.com/fisheye/browse/Zend_Framework/]|[Unsubscribe|mailto:fw-svn-unsubscribe@lists.zend.com]|[fw-svn-subscribe@lists.zend.com|mailto:fw-svn-subscribe@lists.zend.com]|[http://framework.zend.com/fisheye/browse/Zend_Framework/]|
|[Web Services|http://framework.zend.com/wiki/x/zhM]|[Unsubscribe|mailto:fw-webservices-unsubscribe@lists.zend.com]|[fw-webservices-subscribe@lists.zend.com|mailto:fw-webservices-subscribe@lists.zend.com]| |

h3. How to Subscribe
<p>The <a href="http://framework.zend.com/issues/browse/ZF">issue tracker</a> is the place to submit issues of all types. This includes bugs, change requests, feature requests, and small patches. See <ac:link><ri:page ri:content-title="Submitting a Bug Fix" /></ac:link>. If large enough, feature requests should be <a href="http://framework.zend.com/wiki/display/ZFPROP">submitted as a proposal</a>. The issue tracker is also the place to track the <a href="http://framework.zend.com/issues/browse/ZF?report=com.atlassian.jira.plugin.system.project:roadmap-panel">release roadmap</a> and view the current status of framework components.</p>

Please remember to subscribe the email address you use to post messages. Using a different email address may result in substantial delays or a lost message, since we manually review and approve non-spam messages received from email addresses not subscribed to a mail list.
You may subscribe to each list individually, according to your preference,
or you may use a shortcut to subscribe to all the lists, except fw-announce, fw-general, fw-docs, fw-svn. The shortcut is "[fw-all@lists.zend.com|mailto:fw-all@lists.zend.com]".
Do *not* subscribe to both fw-all and one of the lists grouped under fw-all, or you will get *duplicate* messages.
To subscribe, send a mail to LISTNAME-subscribe@lists.zend.com
- e.g. fw-mvc-subscribe@lists.zend.com
<p>If you find yourself constantly submitting patches and having the need for direct access to the Subversion repository, ask and your request will be considered. Please read the <ac:link><ri:page ri:content-title="Subversion Standards" /></ac:link> before submitting code via Subversion.</p>

h3. How to Unsubscribe
<p>To be assigned an issue, you must sign the CLA.</p>

Every mail sent by a list contains mail headers (Control-U in Thunderbird to view). For example:
* List-Post: <mailto:fw-core@lists.zend.com>
* List-Help: <mailto:fw-core-help@lists.zend.com>
* List-Unsubscribe: <mailto:fw-core-unsubscribe@lists.zend.com>
* List-Subscribe: <mailto:fw-core-subscribe@lists.zend.com>
<p>Please read <ac:link><ri:page ri:content-title="Issue Tracker Tips" /></ac:link> before working on issues.</p>

h2. Project Teams
<h2>Review Subversion commits</h2>

I'm excited to report we now have formation of project teams around both team wiki pages and team-specific mail lists!
<p>As code comes into Subversion, it is displayed in our <a href="http://framework.zend.com/code/">WebSVN browser</a> with the changesets listed with full diffs. Review commits and double-check the work of others&mdash;the more eyes, the better. This is also a great way to get a feel for the framework coding style and culture.</p>

Andi Gutmans wrote:
{quote}The idea behind separating the various related components into separate mailing lists and having bigger teams is that it'll enable better inter-component design and architecture, plus it is our experience that having these discussions in bigger groups (which previously were held most directly with Zend) will foster an environment where ideas+proposals are more mature and less work needs to be done afterwards (it will significantly shorten any peer review process).{quote}
<h2>Review and submit a proposal</h2>

h3. Project Team Wiki Pages
* team members (add yourself if your name is missing)
* team's ZF components
* who is working on which components, including coordinators
* major milestones
* tasks needed to accomplish milestones
* what help is needed (very important)
<p>Proposals are contributed by developers and end-users of the Zend Framework. Our <a href="http://framework.zend.com/wiki/display/ZFPROP/Home">proposal wiki space</a> shows the current status of proposals and manages the review process. Submit new proposals here, or help review other submissions as part of our collective intelligence.</p>

h3. Project Team Responsibilities
Each project team is responsible for producing status updates / newsletters:
* Zend project team members will help and work with community members on each team
* copy emailed to fw-general and team-specific mail list
* publish update every two weeks to wiki
* all team members can help update the team's wiki page
* all team members can help author a wiki page containing the status update
<h2>Learn PHPUnit</h2>

We need *each* team to study the other team's wiki pages and borrow
ideas to improve their wiki team page. The pages don't need to be
identical, and some things will work better for different teams. Don't
be afraid to improve something I edited. Be creative =)
<p>Zend Framework development is backed by extensive unit testing. We use <a href="http://www.phpunit.de/wiki/Main_Page">PHPUnit</a> extensively as our testing framework. For code to be accepted, it <strong>must</strong> be tested and covered by a unit test. Please see our <ac:link><ri:page ri:content-title="Testing Standards" /><ac:link-body>testing standards guide and tutorial</ac:link-body></ac:link> for more information.</p>

Also, coordinators and everyone else should help identify tasks and
things to list under "help wanted" sections. We are an open community,
and each project team should be receptive and open to finding areas
for community members to help.
<p>Developers are expected to keep documentation and unit tests in sync with changes to code.</p>

h2. Review the Coding Standards
<h2>Review the coding standards</h2>

All framework code is covered by the [Zend Framework PHP Coding Standard (draft, ZF 0.2 RC1)]. Learn them, love them, live them.
Please "watch" the page above using the "envelope" icon on the upper right side of the page. The Confluence Wiki has a robust email notification system, accessed through your "Preferences" after logging in. From there, click on the "Watches" folder tab, and see the link to "email preferences".
<p>All framework code is covered by the <ac:link><ri:page ri:content-title="PHP Coding Standard (draft)" /></ac:link>. Learn it, love it, live it.</p>

h2. Learn PHPUnit
<p>Please &quot;watch&quot; the page above using the &quot;envelope&quot; icon on the top-right side of the page. Confluence (the wiki system we use) has a robust e-mail notification system, accessed through &quot;Preferences&quot; after logging in. From there, click on the &quot;Watches&quot; folder tab, and see the link to &quot;E-mail preferences&quot;.</p>

Development in the framework is backed by extensive unit testing. We use [PHPUnit|http://www.phpunit.de/wiki/Main_Page] extensively as our testing framework. For code to be accepted, it must be tested and covered by a unit test. Please see our [ZF testing standards guide and tutorial|$2673].
<h2>Learn best practices</h2>

Developers are expected to keep documentation and unit tests in sync with changes to code.
<h3>Common sense</h3>

h2. Contribute to the Wiki
<p>API changes should be committed in parallel with updated documentation.</p>

||Topic||URL||
|Framework \\ Development|[http://framework.zend.com/wiki/display/ZFDEV]|
|Proposals|[http://framework.zend.com/wiki/display/ZFPROP]|
|End-User Wiki|[http://framework.zend.com/wiki/display/ZFUSER]|
<h3>Factory methods, classes, and patterns</h3>

h2. Review and Submit Proposals
<p>For the following, we define &quot;factory&quot; as a class or method that creates instance objects of one or more classes other than the class of the factory.</p>

Proposals are contributed by developers and end-users of the Zend Framework. Our [proposal wiki space|http://framework.zend.com/wiki/display/ZFPROP/Home] shows the current status of proposals and manages the review process. Submit new proposals here, or help review other submissions as part of our collective intelligence.
<p>Direct instantiation is the preferred choice, and factory classes should be avoided if at all possible. Only when sufficient need exists should they be considered. Sometimes the code in a factory method could be moved to a common, shared superclass.</p>

h2. Report, work on, resolve issues in the Issue Tracker
<h3>Container API guidelines</h3>

The [Zend Framework Issue Tracker|http://framework.zend.com/issues/browse/ZF] is the place to submit issues of all types. This includes bugs, change requests, feature requests (if large enough, they could be [submitted as a proposal|http://framework.zend.com/wiki/display/ZFPROP]), and small patches. It is also the place to track the [release roadmap|http://framework.zend.com/issues/browse/ZF?report=com.atlassian.jira.plugin.system.project:roadmap-panel] and view the current status of framework components.
<p>For the time being, we have decided to avoid trying to micromanage implementation details of framework components with containers to suit potential points of reuse throughout the framework. Zend_Session, for example, must wrap a nested PHP array (<code>$_SESSION</code>), not the recursive data structure found in Zend_Config. In a few months, we can revisit this issue and discuss whether implementations of existing components with container data structures should be refactored.</p>

Please read the [Zend Framework Issue Tracker Etiquette] before working on issues.
<p>However, we would like to propose API conventions to help maintain consistency in style for accessing and manipulating container objects, without requiring complicated refactoring of container interfaces, classes, and implementations across diverse components.</p>

h2. Review SVN Commits
<p>When getting and setting data in a random-access container using keys, we suggest the following required, basic operations:</p>

As code comes into SVN, it is displayed in our [Fisheye browser|http://framework.zend.com/fisheye/browse/Zend_Framework] with the change sets listed with full diffs. Review commits and double check the work of others. The more eyes, the better. This is also a great way to get a feel for the framework coding style and culture.
<ul>
<li><code>__get()</code></li>
<li><code>__set()</code></li>
<li><code>__isset()</code></li>
<li><code>__unset()</code></li>
</ul>

h2. Contribute Code

Code can be submitted as patches (via the [issue tracker|http://framework.zend.com/issues/browse/ZF]), or directly to SVN. See [user-contributed notes for how to make patches|http://framework.zend.com/wiki/x/8wU]. Component leads and significant contributors are given direct access to the SVN repositories. If you find yourself constantly submitting patches and having the need for greater access, ask and your request will be considered. Please read the [Zend Framework Subversion Standards] before submitting new code via SVN.
<p>When appropriate, containers should also implement the standard PHP Countable and Iterator interfaces, if only to facilitate debugging by those using the container class.</p>

h2. Best Practices
<p>If the keys used for getting and setting use characters not permitted in PHP identifiers, then use methods named <code>get()</code>, <code>set()</code>, <code>isset()</code>, and <code>unset()</code> instead of the magic methods. Due to the international flavor of Zend Framework, please carefully consider whether those speaking other languages will need to use <code>get($propName)</code> and <code>set($propName, $value)</code>. Using consistently-named methods for the same purpose across multiple classes increases readability and ease of use. Mixing the <code>$object-&gt;propName</code> and <code>$object-&gt;get('propName')</code> styles, on the other hand, can lead to confusion. Pick one and be consistent.</p>

h3. Common Sense
<p>Only implement ArrayAccess and <code>__call()</code> if they are relevant and do not overlap in functionality with the other accessors.</p>

* API changes should be committed in parallel with updated documentation.
<ac:macro ac:name="note"><ac:parameter ac:name="title">Please note</ac:parameter><ac:rich-text-body><p>This section discusses accessing items in a container data structure, not other properties of the object wrapping the container. Accessor methods for these other properties might have different requirements. Defined extension points should be represented by normal functions to access the properties they encapsulate.</p></ac:rich-text-body></ac:macro>

h3. Factory Methods, Classes, and Patterns
<h2>Join a project team</h2>

For the following, we define "factory" as a class or method that creates instance objects of one or more classes other than the class of the factory.
<p>Zend Framework development is done on the basis of large teams working together on related components. It is our experience that having these discussions in bigger groups (which previously were held most directly with Zend) fosters an environment where ideas and proposals are more mature, and also where less work needs to be done afterward due to a significantly shortened peer review process.</p>

Direct instantiation is the preferred choice, and factory classes should be avoided by default, and used only when sufficient need exists.
<h3>Project team wiki pages</h3>

Sometimes the code in a factory method could be moved to a common, shared superclass.
<ul>
<li>Team members (add yourself if your name is missing)</li>
<li>Team's components</li>
<li>Who is working on which components, including coordinators</li>
<li>Major milestones</li>
<li>Tasks needed to accomplish milestones</li>
<li>What help is needed (very important!)</li>
</ul>

h3. ZF Container API Guidelines

For now, we decided to avoid trying to micro-manage implementation details of ZF classes with containers to suit potential points of reuse throughout the framework. Zend_Session, for example, must wrap a nested PHP array ($_SESSION), not the recursive data structure found in Zend_Config. In a few months, we can revisit and discuss whether implementations of existing ZF classes with container data structures should be refactored.
<h3>Project team responsibilities</h3>

Instead, we would like to propose API conventions to help maintain consistency in style for accessing and manipulating container objects, without requiring complicated refactoring of container interfaces, classes, and implementations across diverse ZF components.
<p>Each project team is responsible for producing status updates in the form of newsletters.</p>

When getting and setting *data* in a random-access container using keys, we suggest the following required, basic operations:
* get
* set
* isset
* unset
<ul>
<li>Zend project team members help and work with community members on each team</li>
<li>Newsletters are to be mailed to fw-general and the team-specific mailing list</li>
<li>Updates are to be published every two weeks to the wiki</li>
<li>All team members can help update the team's wiki page</li>
<li>All team members can help author a wiki page containing the status update</li>
</ul>

When appropriate, containers should also implement the standard PHP Countable and Iterator interfaces, if only to facilitate debugging by those using the container class.

If the keys used for getting and setting use characters not permitted in PHP identifiers, then use methods named "get", "set", "isset", and "unset", instead of a "fluent" style interface using magic methods. Using consistently named methods for the same purpose across multiple classes increases readability and ease of use.
<p>We need each team to study the other team's wiki pages and borrow ideas to improve their wiki team page. The pages don't need to be identical, and some things will work better for different teams. Don't be afraid to improve something someone else edited. Be creative!</p>

Only implement ArrayAccess and __call(), if they are relevant and do not overlap in functionality with the other accessors.
<p>Also, coordinators and everyone else should help identify tasks to list under &quot;Help Wanted&quot; sections. We are an open community, and each project team should be receptive and open to finding areas for community members to help.</p>

Intermixing "$object->propName" with "$object->get('propName')" styles can lead to confusion. Pick one and be consistent. Also, if "propName" is not a valid PHP identifier (e.g. contains whitespace or UTF-8), use the "\->get" / "\->set" style. Due to the international "flavor" of ZF, please carefully consider whether those speaking other languages will need to use "get($propName)" and "set($propName, $value)".
<h2>Contribute code</h2>

{info}This section discusses accessing items in a container data structure, not other properties of the object wrapping the container. Thus, accessor methods for these other properties might have different requirements, like defined extension points should be represented by normal functions to access the properties they encapsulate.{info}
<p>Component leads and significant contributors will be granted direct access to the Subversion repository. Please read the <ac:link><ri:page ri:content-title="Subversion Standards" /></ac:link> before submitting new code via Subversion.</p>